1.1 POST の考慮事項¶

「 POST API リクエストデータの例 」に示すデータを使用します。

[Pagination] タブで [Obtain the "next page" token from an HTTP header of the response] を選択します。

次に、次のページの URL を生成するために使用する値を格納するトークンの名前を [HTTP header] に入力します。

たとえば、サーバーは、 "header-token: 1003" など、取得する次のアイテムを示す値を持つ header-token ヘッダーを追加できます。

2.1 REST¶

[Pagination] タブで [Obtain the "next page URL" from the response] を選択します。つづいて、応答に記述された、次のページの URL を指定する名前を [Path to "next" URL in response] に入力します。

たとえば、アクセスする API が以下のような JSON ドキュメントを返すとします。

{
 "name": "p_echo",
 "elements": [{
         "customer_id": "1"
     }, {
         "customer_id": "2"
     }, {
         "customer_id": "3"
     }
 ],
 "links": [{
         "rel": "next",
         "title": "Next interval",
         "href": "http://rest-api.acme.com/my_service?$start_index=10&$count=10"
     }
 ]
}

[Path to "next" URL in response] には「 /links/href 」と入力します。構文は XML データソースの場合と同じです。XML データソースでは、URL を使用してエレメントを探すときに名前空間が考慮されません。

クエリでこのデータソースを扱っている場合、データソースは以下のように動作します。

1. データソースは、[Configuration] タブに示された URL にリクエストを送信します。

2. [Path to "next" URL in response] で指定されたエレメントが応答に存在する場合、データソースはその値を読み込んで、その URL にリクエストを送信します。

   応答から取得した値が「http」で 始まらない 場合、データソースは、データソースの URL ([Configuration] タブの [URL] フィールドの値) のプロトコル (HTTP または HTTPS) とホスト名をコピーして、次のリクエストの URL を作成します。

3. データソースは、 応答の「次の」 URL へのパス が応答に 存在しなくなる か、[Maximum number of requests] フィールドで指定された値にリクエストの数が到達するまで、リクエストを送信し続けます。

「 共通の挙動 」も参照してください。

2.2 POST¶

「 POST API リクエストデータの例 」に示すデータを使用します。

ここでは、その本文を含むリクエストを POST API に送信します。受信する応答は、前述の JSON ドキュメントと同様です。フィールドの名前は、API 実装に応じて異なります。

[Pagination] タブで [Obtain the "next page" token from the response] を選択します。つづいて、応答を処理して次のページの URL を作成するために使用する名前を [Path to next page in the response] に入力します。

[Path to "next" page in response] には「 /id-offset 」と入力します。構文は XML データソースの場合と同じです。XML データソースでは、URL を使用してエレメントを探すときに名前空間が考慮されません。

クエリでこのデータソースを扱っている場合、データソースは以下のように動作します。

1. データソースは、[Configuration] タブに示された URL にリクエストを送信します。

2. [Path to "next" page in response] で指定されたエレメントが応答に存在する場合、データソースはその値を読み込んで、その URL にリクエストを送信します。

   応答から取得した値が「http」で 始まらない 場合、データソースは、データソースの URL ([Configuration] タブの [URL] フィールドの値) のプロトコル (HTTP または HTTPS) とホスト名をコピーして、次のリクエストの URL を作成します。

3. データソースは、応答に has-more フィールドが 含まれなくなる か、[Maximum number of requests] フィールドで指定された値にリクエストの数が到達するまで、リクエストを送信し続けます。

「 共通の挙動 」も参照してください。

2.3 共通の挙動¶

• [Parameter in URL for page size] と [Page size] に値が指定されている場合、データソースでは、送信するすべてのリクエストの URL にクエリパラメータ <Parameter in URL for page size>=<Page size> を追加します。

• [Path to "next" URL in response] が配列フィールドの場合、データソースは、配列の最初のエレメントを読み込みます。URL が配列の 2 番目以降のエレメントに存在する場合、データソースは配列から URL を読み込めません。

• API のレスポンスの中で、次ページの URL を含むフィールド名に「/」文字が含まれる場合、この文字に「/」を追加してエスケープする必要があります。たとえば、[Path to "next" URL in response] のフィールド名が「next/link」の場合、次のように入力してください。

  /pagination/next//link
  

OAuth 1.0a¶

ここでは、OAuth 1.0a 認証を使用するサービスからデータを取得するように「HTTP クライアント」ルートを構成する手順について説明します。管理ツールには、OAuth 1.0a 資格情報を容易に取得できるようにする OAuth 1.0a 資格情報ウィザードが用意されています。

以下の手順に従います。

1. [Edit HTTP connection] ダイアログで [Authentication] タブをクリックします。

2. [Authentication] リストで [OAuth 1.0a] を選択します。

3. サービスから提供される クライアント ID と クライアント共有シークレット を入力します。

4. 署名方法を選択します。最も広く使用されている署名は HMAC-SHA1 なので、通常はそれを選択することが適切です。

5. アクセストークン と アクセストークンシークレット をすでに入手している場合、下にあるボックスにそれらを入力して [Ok] をクリックします。

   これらのトークンを入手していない場合、[launch the OAuth 1.0a credentials...] をクリックして、トークン取得を支援するウィザードを開きます。

OAuth 1.0a 資格情報ウィザード¶

1. [Temporary credential request URL]、[Resource owner authorization URL]、および [Token request URL] に適切な値を入力します。

   アクセス先のサービスのドキュメントには、これらの詳細が記載されている必要があります。

2. [Callback URL] を選択します。ウィザードの手順 2 に進むと、ブラウザーで URL を開く必要があります。この URL をブラウザーで指定すると、Virtual DataPort によるデータへのアクセスを認可するためのページが表示されます。先に進むと 確認コード を取得できます。Virtual DataPort では、この確認コードを使用して HTTP リクエストをサービスに送信します。その応答に アクセストークン と アクセストークンシークレット が含まれています。

   [Callback URL] では、サービスから 確認コード を返す方法を指定します。

   注釈

   サービスによっては、オプションを自由に選択できないことがあります。また、特定のリダイレクト URL の使用が求められる場合もあれば、oob などの特定のオプションのみを使用できる場合もあります。

   1. oob: このオプションを選択すると、認証プロセスの後でブラウザーに 確認コード を表示することが、ウィザードからサービスに要求されます。

   2. 2 番目または 3 番目のオプションを選択すると、それぞれの URL にブラウザーがリダイレクトされ、そこにパラメータ code が追加されます。このパラメータの値が 確認コード です。

      デフォルトの URL (http://localhost:9090/oauth/1.0a/callbackURL.jsp) は、Denodo Platform に組み込まれている Apache Tomcat に存在する JSP を 参照 しています。そこでは、パラメータ code の値がボックスに表示されるので、容易にコピーできます。

      別のコールバック URL を指定する必要がある場合、その URL からパラメータ code の値を手動で抽出する必要があります。

3. [Generate the authorization URL] をクリックします。Virtual DataPort から 一時トークン が要求され、それを使用して 認可 URL が生成されます。

4. [Open URL] をクリックします。ブラウザーを起動していない場合は、URL をコピーして手動でブラウザーを開きます。

   この URL で、サービスからデータを取得する操作を Virtual DataPort サーバーに認可する必要があります。

5. データへのアクセスを Virtual DataPort に認可すると、サービスから 確認コード が返されます。このコードを [Paste the verification code] テキストフィールドに入力します。

   [Callback URL] で [oob] を選択していた場合は、確認コードの値を入力する必要があります。デフォルトの URL を選択していた場合は、確認コードをコピーしてこのボックスに貼り付けることができます。

6. [Obtain the OAuth 1.0a credentials] をクリックします。Virtual DataPort サーバーは、入力されたすべての詳細情報と 確認コード を使用して、OAuth トークンを要求します。

7. [Ok] をクリックしてウィザードを閉じます。

   ウィザードによって [OAuth access token] と [OAuth access token secret] の各テキスト領域に値が入力されます。

6. [Ok] をクリックして [Edit HTTP Connection] ダイアログを閉じます。つづいて、[Save] をクリックするとデータソースが作成されます。

このウィザードを単独で使用するには、管理ツールの [Tools] > [OAuth credentials wizards] メニューで [OAuth 1.0a wizard] をクリックします。

OAuth 資格情報を入力パラメータとするカスタムラッパーを使用する場合は、このウィザードを使用する必要があります。

OAuth 2.0¶

ここでは、OAuth 2.0 認証を使用するサービスからデータを取得するように「HTTP クライアント」ルートを構成する手順について説明します。管理ツールには、OAuth 2.0 資格情報を容易に取得できるようにする OAuth 2.0 資格情報ウィザードが用意されています。

管理ツールには、OAuth 2.0 資格情報を容易に取得できるようにする OAuth 2.0 資格情報ウィザードが用意されています。

データソースでの OAuth 2.0 認証の構成¶

以下の手順に従います。

1. [Edit HTTP connection] ダイアログで [Authentication] タブをクリックします。

2. [Authentication] リストで [OAuth 2.0] を選択します。

3. [Authentication grant] で適切なオプションを選択します。

   1. Authorization code grant: サービスに登録しているユーザー名とパスワードを入力する必要がないことから、これが最も安全なオプションです。取得する必要があるのは「アクセストークン」と「更新トークン」のみであり、どちらもこのダイアログのウィザードを使用して取得できます。この付与方法には、(サービスにもよりますが) 通常はこのデータソースで実行できる操作を制限できるという利点もあります (データへの読み込みアクセスのみ許可するなど)。また、アクセストークンや更新トークンが侵害された場合、このサービスのユーザーアカウントのパスワードを変更しなくても、それらのトークンを無効にすることができます。

   2. [Resource owner password credentials]

   3. [Client credentials grant]

   この 2 番目と 3 番目のオプションは、アクセストークンも更新トークンも取得する必要がないので、1 番目のオプションより構成が簡単ですが、1 番目のオプションにあるような利点は得られません。

   使用可能なオプションについては、このサービスのドキュメントを参照してください。

   これらのオプションの詳細については「 RFC 6749 - The OAuth 2.0 Authorization Framework 」を参照してください。

4. [Client identifier] と [Client secret] に、サービスから提供された情報を入力します。

5. [Resource owner password credentials] を選択した場合のみ、[User identifier] と [User password] を入力します。

6. [Authentication method used by the authorization servers] のいずれかのオプションを選択します。これは、Virtual DataPort から新しい OAuth アクセストークンを要求する際にユーザーの資格情報をサービスに送信する方法を制御します。以下のオプションがあります。

   1. Include the client credentials in the body of the request: リクエスト本文のパラメータ client_id および client_secret として資格情報を追加します。

   2. Send client credentials using the HTTP Basic authentication scheme: HTTP リクエストの Authentication ヘッダーで資格情報を送信します。

   これら 2 つのオプションについては、OAuth 2.0 仕様 (RFC 6749 - The OAuth 2.0 Authorization Framework) の「2.3.1. Client Password」を参照してください。

   1 番目のオプションのほうが広く使用されていますが、サービスによっては 2 番目のオプションを必要とするものがあります。

7. すでに OAuth アクセストークンを入手している場合、それを [Access token] ボックスに入力し、[Request signing method] で適切なオプションを選択します。更新トークンも入手している場合は、それを [Refresh token] ボックスに入力します。トークンのエンドポイント URL の値を [Token endpoint URL] に入力し、アクセストークンの有効期間 (秒数) がわかっている場合はその値も入力します。

   アクセストークンが未入手で、データソースにアクセストークンを保存しておくのではなく、実行時にアクセストークンを指定する場合は、[Access token value is an interpolation variable] をチェックして、その下のボックスにトークンの補間変数の名前を入力します。実行時には、このデータソースの基本ビューに対して実行するクエリで、この補間変数の値を指定する必要があります。この値が、データソースへの接続で使用するアクセストークンになります。OAuth 2.0 認証を要求するソースであっても、その仕様を全面的には実装していない場合に、このオプションが効果的です。この場合は、このトークンを取得して基本ビューに渡すストアドプロシージャを開発するという方法もあります。

   アクセストークンが未入手で、データソースからトークンを入手する場合は、[launch the OAuth 2.0 credentials...] をクリックして、トークンを容易に入手できるようにするウィザードを開きます。

OAuth 2.0 資格情報ウィザード¶

1. [Token endpoint URL] を入力します。

2. [Authorization code grant] を選択した場合のみ、[Authorization server URL] を入力します。

3. [Authorization code grant] を選択した場合のみ、[Redirect URI] を選択します。このウィザードの手順 2 に進むと、ブラウザーで URL を開く必要があります。この URL をブラウザーで指定すると、Virtual DataPort によるデータへのアクセスを認可するためのページが表示されます。

   先に進むと、サービスによって [Redirect URI] の URI にブラウザーがリダイレクトされ、そこにいくつかのパラメータが追加されます。Virtual DataPort では、これらのパラメータの値を使用して、HTTP リクエストをサービスに送信します。その応答に アクセストークン が含まれるほか、 更新トークン が付随することもあります。

4. 追加するスコープごとに ボタンをクリックして、その名前を入力します。

   スコープは、サービスで定義される「権限」であり、アプリケーションが要求できるデータを制御します。

   たとえば、Twitter ではさまざまなスコープが定義されています。このウィザードで要求したスコープによっては、Virtual DataPort でユーザーのツイートを取得できますが、ユーザーの代わりに新しいツイートを送信することはできません。

前のダイアログで [Authorization code grant] を選択している場合は、この後の手順の e. から h. までのみを実行します。

5. 通常、[Set the "state" request] パラメータは選択したままでかまいません。ただし、OAuth 資格情報の取得プロセスが失敗した場合は、このパラメータを選択することがサービスで許可されていることを確認します。

6. [Generate the authorization URL] をクリックします。

   Virtual DataPort によって、指定したすべてのパラメータを使用して URL が生成されます。

7. [Open URL] をクリックします。

   ブラウザーを起動していない場合は、URL をコピーして手動でブラウザーを開きます。

   この URL で、サービスからデータを取得する操作を Virtual DataPort サーバーに認可する必要があります。

8. アプリケーションを認可すると、サービスによってリダイレクトされます。このリダイレクト先の URL を手順 3 のテキストフィールドに貼り付けます。

9. [Obtain the OAuth 2.0 credentials] をクリックします。

   Virtual DataPort サーバーから、入力したすべての詳細情報、および前の手順で貼り付けた URL のパラメータを使用して OAuth 資格情報が要求されます。

10. [Ok] をクリックしてウィザードを閉じます。

    ウィザードによって、サービスから返された情報がテキスト領域とテキストフィールドに入力されます。

    すべてのサービスが 更新トークン を提供するわけではないので、このテキスト領域が空になることも考えられます。

8. [Request signing method] を選択します。Virtual DataPort は、 アクセストークン を使用して各リクエストに署名する必要があります。通常は、すべての OAuth サービスで、["Authorization" request header] を使用できます。これは、特殊な HTTP ヘッダーをリクエストに追加する方法です。この方法をサポートしていないサービスについては、以下に示すように、標準で定義されている他の方法を選択できます。

   1. Form-encoded body parameter: リクエストの本文でトークンを送信します (HTTP の POST リクエストでのみ使用可能)。

   2. URL query parameter ("access_token"): URL のパラメータ access_token でトークンを送信します。

   3. URL custom query parameter: "access_token" とは別の名前のクエリパラメータとしてトークンを追加します。

9. アクセストークンが未入手で、データソースにアクセストークンを保存しておくのではなく、実行時にアクセストークンを指定する場合は、[Refresh token value is an interpolation variable] をチェックして、その下のボックスにトークンの補間変数の名前を入力します。実行時には、このデータソースの基本ビューに対して実行するクエリで、この補間変数の値を指定する必要があります。必要に応じ、この値を使用してアクセストークンが更新されます。OAuth 2.0 認証を要求するソースであっても、その仕様を全面的には実装していない場合に、このオプションが効果的です。この場合は、このトークンを取得して基本ビューに渡すストアドプロシージャを開発するという方法もあります。

10. OAuth 2.0 認証を使用する REST API の中には、クライアントによる追加のパラメータの送信が必要になるものがあります。[Extra parameters of the refresh token requests] をクリックしてパラメータを追加してください。Denodo によって、パラメータが以下のどちらかのリクエストに追加されます。

    1. アクセストークンを初めて取得するリクエストで送信。[OAuth Credentials Wizard] で [Obtain the OAuth 2.0 credentials] をクリックしたときに生成される URL にパラメータを追加します。

    2. データソースがアクセストークンを更新するリクエストで送信。現在のアクセストークンが期限切れとなった場合、データソースは更新トークンを使用して新しいアクセストークンを取得する必要があります。

    たとえば、クラウド上の Microsoft サービスに OAuth 2.0 認証を使用して接続する場合、パラメータ resource を追加する必要があるでしょう。その値は接続先アプリケーションの ID とします。これは、この API による要件です。

    このダイアログで、パラメータの値の横にある [Encrypted] チェックボックスをチェックした場合、データソースはこの値を暗号化した状態で保管します。

11. [Pass-through session credentials] を選択した場合、以下のいずれかのパススルー戦略を選択します。

    重要

    選択した戦略が関連するのは、ユーザーが OAuth 認証を使用して Virtual DataPort にログインした場合のパススルーセッション資格情報のみです。

    • Token exchange flow (RFC 8693): データソースは、 トークン交換フロー (「 RFC 8693 」で定義されている) を使用して、コネクションを確立するためにアクセストークンを取得します。

    • On-behalf-of flow (Azure AD): データソースは、Microsoft 独自の On-behalf-of フローを使用して、コネクションを確立するためにアクセストークンを取得します。

    • OAuth Token pass-through: データソースは、クライアントアプリケーションが Virtual DataPort にログインするために使用したのと同じアクセストークンを使用してソースに接続します。

    さらに、以下に示すようなデフォルト値が入力されたいくつかのフィールドおよび新しいフィールドが表示されます。

    • [Resource owner password credentials] では [Authentication grant] が選択されます。

    • [Include the client credentials in the body of the request] では [Authentication method used by the authorization server] が選択されます。

    • ["Authorization" request header] では [Request signing method] が選択されます。

    • 最後に [Scope] が表示されます。セッションのアクセストークンの有効期限が切れた場合に備えて、新しいアクセストークンを取得するスコープを入力する必要があります。

12. [Ok] をクリックして [Edit HTTP Connection] を閉じます。つづいて、[Save] をクリックするとデータソースが作成されます。

通常、OAuth 2.0 資格情報ウィザードを起動するには、[Create JSON data source] ダイアログまたは [Create XML data source] ダイアログを使用します。ただし、管理ツールの [Tools] > [OAuth credentials wizards] メニューで [OAuth 2.0 wizard] をクリックすることで、このウィザードを単独で使用することもできます。

OAuth 資格情報を入力パラメータとするカスタムラッパーを使用する場合は、このウィザードを使用する必要があります。