REST Web サービスの作成¶
REST Web サービスは、1 つまたは複数のビューのデータを公開し、必要に応じてこれらのビューのアソシエーションを公開します (「 Associations 」を参照)。これらのサービスは、Denodo RESTful Web サービスと同じ RESTful アプローチに従っており、同じように動作しますが、選択したビューのデータとアソシエーションのみを表示するところが異なります。
SOAP Web サービスとの主な違いは、REST Web サービスが「リソース指向」であるのに対して、SOAP Web サービスは「操作指向」であることです。
REST Web サービスは、以下の 4 つの異なるデータ表現を提供します。
HTML
XML
JSON
RSS。これは、
RSS MAPPING VIEW
句を使用してサービスを構成した場合にのみ使用できます。
CREATE [ OR REPLACE ] REST WEBSERVICE <name:identifier>
[ PRESERVE_OPERATIONS ]
CONNECTION (
CHUNKSIZE = <integer>
CHUNKTIMEOUT = <integer>
QUERYTIMEOUT = <integer>
POOLENABLED = <boolean>
POOLINITSIZE = <integer>
POOLMAXACTIVE = <integer>
)
[ DEFAULTREPRESENTATION = <representation> ]
[ SUPPORTEDREPRESENTATIONS = ( <representation> [, <representation> ]* ) ]
[ DISPLAYRESTFULREFERENCES = { TRUE | FALSE } ]
[ AUTHENTICATION ( <authentication> ) ]
[ CUSTOMNAMESPACE = <literal> ]
[ CUSTOMCSS = <css stylesheet:literal> ]
[ VERBOSEERRORS = <boolean> ] // Default value is true
RESOURCES ( <resource config> [, <resource config> ]* )
[ ASSOCIATIONS ( <association name:identifier with database>
[, <association name:identifier with database> ]* ) ]
[ OPTIONS (
[ <RSS mapping> [, <RSS mapping> ]* ]
[ <XSLT config> [, <XSLT config> ]* ]
[ APPLYOUTPUTXSLTTOERRORS ]
[ NULLVALUESASEMPTYXMLELEMENTS = <boolean> ]
[ ALLOW_CORS_ORIGINS ( { * | <literal> [, <literal> ]* } )
{ ENABLED | DISABLED } ]
[ MAX_ROWS_PER_PAGE = <non-zero positive integer> ]
[ PROCESS_FUNCTIONS_IN_SELECT_PARAMETER = <boolean> ]
)
]
[ FOLDER = <literal> ]
[ DESCRIPTION = <literal> ]
<representation> ::=
HTML
| JSON
| RSS
| XML
<authentication> ::=
BASIC <credentials>
| BASIC VDP [ VDPACCEPTEDUSERS <users list> ]
| DIGEST <credentials>
| SPNEGO
| SAML2 <saml2 parameters>
| OAUTH2
<credentials> ::=
USER <user name:literal> PASSWORD <password:literal> [ ENCRYPTED ]
<users list> ::=
<user name:literal> [, <user name:literal> ]*
<saml2 parameters> ::=
SPENTITYID <service provider entity ID:literal>
<resource config> ::=
VIEW <view identifier>
FIELDS ( <fields list> [ <fields' mappings> ] )
<fields list> ::= <field> [, <field> ]*
<field> ::=
<name:literal> : <type:literal>
[ <XPath of the field:literal> = <displayed name:literal> ]
[ <direction> ] [ OBL ] [ UNESCAPED ]
<direction> :: =
INPUT_ONLY
| OUTPUT_ONLY }
<RSS mapping> ::=
RSS MAPPING VIEW <viewName:literal> (
CHANNEL ( <mapping> [, <mapping> ]* )
ITEM ( <item mapping> [, <item mapping> ]* )
)
<mapping> ::=
<rss tag:literal> = <value:literal>
<item mapping> ::=
<rss tag:literal> = <field:identifier>
<XSLT config> ::=
VIEW <viewName:literal> XSLT (
[ INPUTXSLT = <XSLT:literal> { ENABLED | DISABLED } ]
[ OUTPUTXSLT = <XSLT:literal> { ENABLED | DISABLED } ]
)
<view identifier> ::= (「 VQL ステートメントの基本エレメント 」を参照)
<identifier with database> ::= (「 VQL ステートメントの基本エレメント 」を参照)
公開するビューを RESOURCES
句で定義する必要があります。公開するビューごとに、ビューの名前を VIEW
句の後に指定し、また、ビューのフィールド (FIELDS
) を指定する必要があります。ビューのフィールドをすべて公開する必要はありません。
アソシエーションを公開するには、 ASSOCIATIONS
パラメータを追加します。これは公開するアソシエーションの名前のコンマ区切りリストです。
CHUNKSIZE
、 CHUNKTIMEOUT
、 QUERYTIMEOUT
、 POOLENABLED
、 POOLINITSIZE
、および POOLMAXACTIVE
の各パラメータは、Web サービスと Virtual DataPort サーバー間のコネクションを構成します (「 コネクションパラメータ 」を参照)。
DEFAULTREPRESENTATION
パラメータおよび SUPPORTEDREPRESENTATIONS
パラメータは、Web サービスのデフォルトの表現と使用可能な表現を設定します (管理ガイドの「 デフォルト表現と使用可能な表現の選択 」を参照)。
Web サービスによって詳細なエラーメッセージが返されないようにする場合は、 VERBOSEERRORS = false
句を追加します。この句を追加しないか、または true
に設定した場合、Web サービスは、操作の呼び出しでエラーが発生すると詳細なエラーメッセージを返します。メッセージには、問題が発生した箇所、たとえばデータソース接続時のタイムアウトや、クエリ実行時のエラーなどが発生したかどうかが示されます。Web サービスのクライアントがこれらの詳細なメッセージを受け取らないようにする場合は、 VERBOSEERRORS = false
を追加します。
DISPLAYRESTFULREFERENCES
パラメータは、[Create REST Web service] ダイアログの [Display RESTful links] チェックボックスに相当します (管理ガイドの「 [Settings] タブ (REST) 」を参照)。これが FALSE
の場合、実行時に Web サービスはビューのリンクを返しません。
各フィールドの定義で、以下の修飾子はフィールドのステータスに相当します。
OBL
: 必須フィールドINPUT_ONLY
: 出力しないOUTPUT_ONLY
: 検索不可
UNESCAPED
は、実行時に、このフィールドの値が HTML でエスケープされないことを示します (管理ガイドの「 データの HTML エスケープ 」を参照)。
サービスの認証設定は、 AUTHENTICATION
パラメータで制御します。
RSS 形式は、アイテムごとに固有の一連のフィールドを指定します。したがって、ビューを RSS 形式でエクスポートするときに、ビューのフィールドと RSS 形式のフィールドとの対応関係を指定する必要があります。これは、 MAPPING
句で行うことができます。RSS フィードには、フィードに関する一般的な情報を指定する channel
エレメントが含まれています。 MAPPING
句の CHANNEL
パラメータを使用すると、RSS 形式で許可されている各 channel
サブエレメントの定数値を指定できます。RSS フィードには、 item
エレメントのリストが含まれています。Virtual DataPort は、サービスで使用されるビューに対して実行されるクエリによって返されるタプルごとに、 item
エレメントを生成します。 MAPPING
句の ITEM
パラメータを使用すると、RSS 形式で定義されている各 item
サブエレメントに対応するビューの属性を選択できます。RSS 形式では、少なくとも 1 つの値を title
サブエレメントまたは description
サブエレメントのいずれかに割り当てる必要があります。
デフォルトでは、XSLT 変換はデータに適用されますが、Web サービスによって返されるエラーメッセージには適用されません。XSLT 変換をエラーメッセージにも適用させる場合は、 APPLYOUTPUTXSLTTOERRORS
句を追加します。
これは、サービスの XML 表現にのみ影響を及ぼします。
デフォルトでは、Denodo REST Web サービスは、 xsi:nil="true"
属性をエレメントに追加することによって、フィールドの値が NULL
であることを明示的に指定します。たとえば、ある行の field_name フィールドの値が NULL
の場合、サービスは以下を返します。
<field_name xsi:nil="true" />
Web サービスで xsi:nil="true"
属性を使用して NULL
値を指定しない場合、 NULLVALUESASEMPTYXMLELEMENTS = TRUE
句を追加します。これにより、 NULL
値は空のエレメント (<field_name />
など) で表されます。このオプションを有効にした場合、テキストフィールドでは、 NULL
値と空の文字列との間に違いがないという問題があります。
この句を追加しない場合、 NULLVALUESASEMPTYXMLELEMENTS = FALSE
を追加した場合と等しくなります。
これは、ビューの XML 表現のみに当てはまることに注意してください。
REST Web サービスでオリジン間リソース共有 (CORS) のサポートを有効にできます。CORS の詳細については、管理ガイドの「 オリジン間リソース共有 (CORS) 」を参照してください。
このサポートを有効にするには、 ALLOW_CORS_ORIGINS
句を追加して、このサービスがリクエストを受け取ることができるドメインを指定します。
「 ALLOW_CORS_ORIGINS ( * )
」と入力すると、すべてのドメインからの CORS リクエストを許可できます。
または、「 ALLOW_CORS_ORIGINS ( <list of allowed domains> )
」と入力します。 <list of allowed domains>
は、このサービスに対するリクエストを許可する URL のコンマ区切りリストです。たとえば、「 ALLOW_CORS_ORIGINS ( http://foo.com, https://foo.bar.com )
」のように入力します。
許可されるドメインのリストを設定する場合、それ以外のドメインからの CORS リクエストは、HTTP コード 403 (Forbidden) で拒否されます。
重要
URL ごとに、そのプロトコルも入力します。プロトコルが含まれていない URL は無効です。たとえば、 ALLOW_CORS_ORIGINS ( foo.com )
は無効です。
サービスによって返される行の数を制限できます。この制限を有効にすると、クライアントがビューに対してクエリを実行した場合に、応答内の行の数はこの制限を超えなくなります。この機能は、Virtual DataPort サーバーやそのデータソースに過度の負荷をかけるクライアントが存在しないようにする場合に役立ちます。
この制限を有効にするには、 MAX_ROWS_PER_PAGE = <non-zero positive integer>
パラメータを OPTIONS
句に追加します。
PROCESS_FUNCTIONS_IN_SELECT_PARAMETER = TRUE
パラメータを追加するのは、管理ツールにおける REST Web サービスの構成で、[Advanced] タブの [Process functions in $select parameter] チェックボックスを選択するのと同じことです。
このオプションについては、管理ガイドの「 [Advanced] タブ (REST) 」を参照してください。
既存の REST クライアントおよびサービスがある環境では、Virtual DataPort Web サービスで動作するようにこれらのクライアントを変更する必要はありません。XSLT スタイルシートを定義することによって、受信 XML メッセージを変換し、新しい Web サービスで必要な形式にそれらを適応させることができます。また、スタイルシートを定義して、XML 応答を変換してから既存のクライアントに送信することもできます。これを行うには、 XSLT
パラメータを使用します。
詳細については、管理ガイドの「 XSLT 変換 」を参照してください。
PRESERVE_OPERATIONS
句は、 CREATE OR REPLACE
操作でのみ使用できます。このトークンは、同名の Web サービスが存在する場合、そのリソースが保持され、リソース名が競合する場合は置換されることを示します。