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 REST WEBSERVICE ステートメントの構文
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>

<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 } ]
  )

公開するビューを RESOURCES 句で定義する必要があります。公開するビューごとに、ビューの名前を VIEW 句の後に指定し、また、ビューのフィールド (FIELDS) を指定する必要があります。ビューのフィールドをすべて公開する必要はありません。

アソシエーションを公開するには、 ASSOCIATIONS パラメーターを追加します。これは公開するアソシエーションの名前のコンマ区切りリストです。

CHUNKSIZECHUNKTIMEOUTQUERYTIMEOUTPOOLENABLEDPOOLINITSIZE 、および 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 サービスが存在する場合、そのリソースが保持され、リソース名が競合する場合は置換されることを示します。