USER MANUALS

[Settings] タブ (REST)

このタブでは、REST Web サービスの以下のパラメータを構成できます。

Creating a REST Web service: Settings tab

REST Web サービスの作成: [Settings] タブ

  • 各操作に対して以下を設定できます。

    • HTML エスケープ (「 データの HTML エスケープ 」を参照) しないフィールドを選択する。

    • RSS マッピング (「 RSS 表現のマッピング 」を参照) を割り当てる。

    • 既存の REST-XML クライアントの要件に適応するように、この操作に対するリクエストと応答を変換する XSLT 変換 を定義する。「 XSLT 変換 」を参照してください。

  • デフォルトでは、XSLT 変換はデータに適用されますが、Web サービスによって返されるエラーメッセージには適用されません。XSLT 変換をエラーメッセージにも適用する場合は、[Apply output XSLT to error messages] を選択します。これは、ビューの XML 表現にのみ影響を及ぼします。

  • Web サービスが詳細なエラーメッセージを返すかどうか: デフォルトでは、Denodo Web サービスは、操作の呼び出し中にエラーが発生した場合、詳細なエラーメッセージを返します。メッセージには問題が発生した箇所が示されます (たとえば、いずれかのデータソースに接続中にタイムアウトが発生したかどうかや、クエリの実行中にエラーが発生したどうか)。Web サービスのクライアントがこれらの詳細なメッセージを受け取らないようにするには、[Display verbose error messages] チェックボックスのチェックをはずします。その場合、サービスは単純なエラーメッセージを返します。

  • Web サービスで提供する表現を選択します。「 デフォルト表現と使用可能な表現の選択 」を参照してください。

  • サービスによって返される行の数を制限します。この制限を有効にすると、クライアントがビューに対してクエリを実行した場合に、応答内の行の数はこの制限を超えなくなります。この機能は、Virtual DataPort サーバーやそのデータソースに過度の負荷をかけるクライアントが存在しないようにする場合に役立ちます。

    この制限を有効にするには、[Limit the size of the responses] チェックボックスをチェックして、必要に応じて [Maximum number of rows] ボックスでデフォルトの制限を変更します。

  • デフォルトでは、REST Web サービスは、ビューのデータ内で以下のようにさまざまなリンクを返します。

    • ビューの各行に、行自体を参照するリンクが 1 つ存在します。

    • 各行に、公開されているビューのアソシエーションごとにリンクが 1 つ存在します。

    • JSON 表現と XML 表現に、結果自体を参照するリンクが 1 つ存在します。

    これらのリンクを結果に含めないようにする場合、[Display RESTful links] チェックボックスのチェックをはずします。

  • XML 表現は、デフォルトの名前空間を使用します。この名前空間は変更可能です。これを行うには、[Custom XML namespace] をクリックします。

  • デフォルト以外の CSS ドキュメント を提供します。これは、Web サービスの HTML 表現でのみ有効です。このサービスの CSS をカスタマイズしない場合は、グローバル RESTful Web サービスと同じ CSS が使用されます。グローバル RESTful Web サービスの CSS はカスタマイズ可能 (「 RESTful Web サービスの表示と操作性のカスタマイズ 」で説明) なので、すべての REST サービスがカスタマイズされた同一のレイアウトを使用するように簡単にセットアップできます。

  • サービスの 認証 方法を構成します。「 Web サービスの認証 」を参照してください。

  • Web サービスでオリジン間リソース共有 (CORS) を有効にします。「 オリジン間リソース共有 (CORS) 」を参照してください。

データの HTML エスケープ

デフォルトでは、REST Web サービスの HTML 表現は、 text 型の値をすべて「HTML エスケープ」します。たとえば、フィールドの値が <a href="http://www.denodo.com">denodo</a> である場合、ユーザーには http://www.denodo.com へのリンクではなくテキストとして表示されます。

フィールドの値を HTML エスケープしない場合、以下の 2 つのオプションがあります。

  1. 設計時に REST Web サービスを定義する際、サービスでエスケープするフィールドを選択します。

  2. 実行時にパラメータ $noescapehtml を URL に追加します。REST Web サービスのこのパラメータおよび他のパラメータを使用する方法については、「 RESTful Web サービスの入力パラメータ 」を参照してください。

設計時に Web サービスを構成するには、[Resource configuration] リストで構成するビューを選択して [HTML escaped fields] をクリックします。[HTML Escaped Fields] ダイアログが開きます。

REST Web services: HTML escaped fields

REST Web サービス: [HTML Escaped Fields]

このダイアログで、サービスでエスケープしないフィールドのチェックボックスのチェックをはずします。

RSS 表現のマッピング

RSS 2.0 形式 (Really Simple Syndication Format (RSS 2.0)) では、アイテムごとに一連の固有のフィールドを指定します。したがって、RSS 形式でビューをエクスポートする場合は、ビューのフィールドと RSS 形式のフィールドとの間の対応を指定する必要があります。RSS マッピング画面では、以下のオプションが表示されます。

  • 公開されているサービスに複数のビューの操作が含まれる場合、そのサービスの RSS バージョンには、その 1 つに対してクエリを実行する操作のみを含めることができます。左上にあるドロップダウンから、使用するビューを選択できます。

  • channel 属性の値。RSS フィードには、フィードの一般情報を指定する channel エレメントが含まれます。このオプショングループで、RSS 形式で使用できる channel サブエレメントそれぞれの定数値を指定できます。

  • チャネルアイテムの属性のマッピング。RSS フィードには、item エレメントのリストが含まれます。Virtual DataPort は、選択したビューに対して実行したクエリから返される各行に対して 1 つの item エレメントを生成します。このオプショングループを使用して、RSS 形式で定義されている各 item サブエレメントに対応するビューの属性を選択できます。特定の item サブエレメントのマッピングの値が「none」のままである場合、そのサブエレメントは出力フィードに含まれません。RSS 形式では、少なくとも 1 つの値が「title」サブエレメントまたは「description」サブエレメントのどちらかに割り当てられている必要があることが規定されています。

デフォルト表現と使用可能な表現の選択

REST Web サービスは、ビューのデータを以下の 4 つの表現で提供できます。

  1. HTML

  2. XML

  3. JSON

  4. RSS

以下の構成が可能です。

  • [Available representations] で、Web サービスで提供する表現を選択します。たとえば、Web サービスで XML 表現と JSON 表現のみを提供し、HTML または RSS を提供しないように指定できます。

  • [Set default representation] をクリックして、データのデフォルト表現を選択します。

リクエストに Accept HTTP ヘッダーが含まれていない場合、または URL でパラメータ $format が指定されていない場合、Web サービスはデフォルト表現を返します。

ブラウザーは常に、HTML 表現をリクエストする Accept ヘッダーを送信します (Accept = text/html, application/xhtml+xml など)。したがって、Web サービスで使用可能な表現の 1 つが HTML である場合、ユーザーがブラウザーを使用してそのサービスに接続すると、サービスは、その「デフォルト表現」に関係なく、HTML 表現を返します。この場合、別の表現を取得するには、URL にパラメータ $format を追加します ($format=xml など)。

Accept ヘッダーに複数のメディアタイプが設定されていて、その中にサービスのデフォルト表現が含まれている場合、サービスはデフォルト表現を返します。ただし、 Accept ヘッダーでデフォルト表現の品質係数が 1 未満である場合、サービスは最も大きい品質係数 (以下の例を参照) の表現を返します。

たとえば、ビューを REST Web サービスとして公開するとします。このサービスで使用可能な表現は JSON と XML で、デフォルト表現は XML です。次の表に、リクエストの Accept HTTP ヘッダーの値に応じた出力のリストを示します。

Accept HTTP ヘッダーに応じて REST Web サービスが返す表現

リクエストの Accept HTTP ヘッダー

出力表現

application/xml

XML

application/json

JSON

application/json, application/xml

XML

リストの先頭のメディアタイプではありませんが、デフォルト表現であるため。

application/xml;q=0.9,application/json

JSON

デフォルト表現 (XML) の品質係数が、サポートされている他の表現の品質係数より小さいため。

application/json;q=0.2,application/xml;q=0.1

JSON

デフォルト表現 (XML) の品質係数が、サポートされている他の表現の品質係数より小さいため。

text/xml, application/rss+xml

Accept ヘッダーのどのメディアタイプもサービスでサポートされていないので、サービスは HTTP エラー 406 (Not Acceptable) を返します。

注釈

RSS 表現を構成する必要があります。したがって、RSS を選択する場合、[RSS mappings] をクリックして構成します。

オリジン間リソース共有 (CORS)

セキュリティ上の理由から、ブラウザーは Web ページの生成元ドメインと異なるドメインを宛先とした HTTP リクエストの実行を Web ページに許可しません。たとえば、HTTP リクエストを送信する JavaScript コードを http://foo.com が提供するページに含めることは可能ですが、デフォルトではこのコードが http://bar.com に置かれた API にリクエストを送信することをブラウザーは許可しません。

オリジン間リソース共有 (Cross-Origin Resource Sharing (CORS)) は、Web ページの生成元ドメインと異なるドメイン宛の HTTP リクエストを実行することを Web ページに許可するかどうかを判断するために、ブラウザーと Web サーバーが情報をやり取りするメカニズムです。その目的は、ドメイン http://foo.com から提供されるページが、ドメイン http://bar.com にあるサーバーにリクエストを送信しても安全かどうかをブラウザーが判断できるようにすることです。

CORS をサポートするように REST Web サービスを構成できます。これにより、サービスは適切な HTTP ヘッダーで応答し、ブラウザーがそのようなリクエストを許可するようになります。こうすることで、このサービスにリクエストを送信する Web ページを作成できます。

CORS の初期設定

更新プログラム 8.0u20210705 以降、Denodo の Web コンテナーは OPTIONS メソッドを使用した HTTP リクエストを拒否しています。初期の更新プログラムでは OPTIONS メソッドが許可されていましたが、OPTIONS メソッドがもたらす情報を攻撃者が悪用して、このサーバーに関する追加情報を取得するおそれがあるため、変更されています。ただし、CORS メカニズムを使用するには、サーバー (つまり、Denodo の Web コンテナー) で OPTIONS メソッドを許可し、必要な情報を提供する必要があります。

したがって、CORS をサポートする Web サービスを最初に公開する前に、次の作業を行ってください。

  1. この Denodo Platform インストール環境のすべてのコンポーネントを停止します。次に、 <DENODO_HOME>/bin/webcontainer_shutdown を実行して Web コンテナーが停止していることを確認します。

  2. <DENODO_HOME>/resources/apache-tomcat/conf/web.xml ファイルを編集します。

  3. 2 つの security-constraint エレメントを探し、その内容をコメントアウトします (「security-constraint」エレメントはそのまま残します)。作業が完了すると、次のような状態になります。

    <security-constraint>
<!--
    <web-resource-collection>
        <web-resource-name>restricted methods</web-resource-name>
        <url-pattern>/*</url-pattern>
        <http-method>OPTIONS</http-method>
     </web-resource-collection>
     <auth-constraint/>
 -->
 </security-constraint>
 <security-constraint>
 <!--
     <web-resource-collection>
     <web-resource-name>restricted methods</web-resource-name>
     <url-pattern>/*</url-pattern>
     <http-method-omission>OPTIONS</http-method-omission>
     </web-resource-collection>
 -->
 </security-constraint>

    「security-constraint」エレメントを削除する必要はなく、内容をコメントアウトするだけです (<!-- と --> を用います)。

  4. 必要なサーバーとツールを起動します。

注釈

OPTIONS メソッドに関して web.xml ファイルで実行された変更を更新後も維持するには、<DENODO_HOME>/resources/apache-tomcat/conf/tomcat.properties 下のプロパティ com.denodo.tomcat.keepOPTIONSMethodConfiguration を true に設定します。

次のいずれかの場合は、Denodo サーバーまたは Solution Manager の管理者に相談してから作業を行ってください。

  • CORS をサポートする Web サービスを初めて公開する場合

  • RESTful Web サービスで CORS のサポートを有効化する場合

  • CORS とともに、Data Catalog と Solution Manager の REST API を使用する場合

Web サービスでの CORS の有効化

REST Web サービスで CORS のサポートを有効にするには、[Enable CORS] を選択します。次に、以下のオプションのいずれかを選択します。

  • Any origin: サービスは、任意のドメインから送信された CORS リクエストを許可します。

  • Origins: このサービスへのリクエストを許可する URL のリストを入力します。各 URL はコンマで区切ります。たとえば、 http://foo.com, https://foo.bar.com のように指定します。

    他の生成元からの CORS リクエストは、HTTP コード 403 (Forbidden) で拒否されます。

    重要

    URL ごとに、そのプロトコルも入力します。プロトコルが含まれていない URL は無効です。たとえば、foo.com は無効です。

Web サービスで CORS サポートを有効にしても、任意のドメインからの通常の HTTP リクエストは引き続き許可されます。

重要

REST Web サービスは、Denodo に組み込まれた Web コンテナーにデプロイされた場合にのみ (つまり、[Web services container] ダイアログで [Deploy] をクリックした場合)、CORS をサポートします。Web サービスを war ファイルにエクスポートして別の Web コンテナーにデプロイする場合は、そのコンテナーで提供されているメカニズムを使用して CORS サポートを構成する必要があります。なぜなら、CORS の構成はすべての Web コンテナーにわたる標準ではないからです。

Denodo REST サービスは、HTTP メソッドの GET、POST、PUT、および DELETE で CORS をサポートします。

OpenAPI/Swagger

OpenAPI 仕様 (OAS) (旧称「Swagger 仕様」) では言語に依存しない標準インターフェイスが定義されており、このインターフェイスを使用することで人間とコンピュータの双方が REST API の機能を見つけて理解できるようになります。

OpenAPI ドキュメントは API を記述するもので、OpenAPI 仕様に従います。

Denodo を使用して公開した REST Web サービスには、Web サービスの操作、入力パラメータ、出力スキーマ、利用可能なメディアタイプ (JSON、XML) などを記述した OpenAPI ドキュメントが含まれます。この OpenAPI ドキュメントを利用すれば、Web サービスとやり取りするアプリケーションを容易に開発できます。

Web サービスでは、OpenAPI ドキュメントの 2 つのバージョン (バージョン 3.0 と 2.0) および OpenAPI ビューアーが提供されます。このビューアーを使用すると、Web サービスのエンドコンシューマーは、Web サービスの操作を簡単に視覚化してテストできます。

REST Web サービスの OpenAPI ドキュメントとビューアーにアクセスするには、Web サービスをデプロイして、その [Summary] パネルに移動し、[OpenAPI specification] の横のリンクをクリックします。あるいは、次の URL に直接アクセスしても構いません。

  1. OpenAPI ビューアー (OpenAPI 3.0 搭載): https://denodo-server.acme.com:9443/swagger-ui?url=https://denodo-server.acme.com:9443/server/<database>/<web service>/OpenAPIv3/openapi.json

  2. OpenAPI バージョン 3.0: https://denodo-server.acme.com:9443/server/<database>/<web service>/OpenAPIv3/openapi.json

  3. OpenAPI バージョン 2.0: https://denodo-server.acme.com:9443/server/<database>/<web service>/OpenAPI/swagger.json

JSON 形式のドキュメントは YAML 形式と同等の内容です。

REST Web サービスのバージョンを指定するには、[Web service version] に値を入力します (デフォルトは「 1.0.0 」)。この値は、OpenAPI 仕様に含まれています。

Virtual DataPort の構成で OpenAPI エンドポイントを無効にすることができます (「 REST Web サービスのグローバル設定 」を参照)。これはグローバル構成であるため、すべての REST Web サービスに影響します。

重要

SwaggerUI では、 ?url パラメータによるリモート OpenAPI 定義の表示に対応しています。この機能はデフォルトで有効です。これを無効にするには、<DENODO_HOME>/resources/apache-tomcat/conf/tomcat.properties ファイルのプロパティ com.denodo.tomcat.swaggerui.queryConfigEnabled を false に設定します。SwaggerUI の URL パラメータを無効にすると、OpenAPI ビューアーでは OpenAPI 定義を読み込めなくなることに注意してください。

Add feedback