外部データソース concept_t2s_kqt_52b
外部データソースを使用すると、サードパーティシステムへの接続を定義できます。例えば、ホテルの予約システムを使用して、部屋が登録されたかどうかを確認する場合などです。組み込みの Adobe Experience Platform データソースとは異なり、外部データソースは必要な分だけ作成できます。
POST または GET を使用して JSON を返す REST API がサポートされています。API キー、基本およびカスタム認証モードがサポートされています。
リアルタイムの天気データに応じて、ジャーニーの動作をカスタマイズするために使用する、天気 API サービスの例を見てみましょう。
以下に API 呼び出しの例を 2 つ示します。
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
呼び出しにはメイン URL（https://api.adobeweather.org/weather）、2 つのパラメーターセット（都市の場合は「city」、緯度と経度の場合は「lat/long」）、および API キー（appid）が含まれます。
新しい外部データソースを作成して構成するための主な手順は次のとおりです。
-
データソースのリストで「データソースを作成」をクリックして、新しい外部データソースを作成します。
画面の右側にデータソース設定ペインが開きます。
-
データソースの名前を入力します。
note note NOTE スペースや特殊文字は使用しないでください。30 文字以内にしてください。 -
データソースに説明を追加します。この手順はオプションです。
-
外部サービスの URL を追加します。この例では、次のようになります。https://api.adobeweather.org/weather。
note caution CAUTION セキュリティ上の理由から、HTTPS の使用を強くお勧めします。また、アドビの非公開アドレスや IP アドレスの使用は許可されていません。 
-
外部サービスの設定に応じて認証を 認証なし、基本、カスタム、API キー のいずれかに設定します。カスタム認証モードについて詳しくは、この節を参照してください。この例では、次を選択します。
- タイプ：API キー
- 値："1234"（API キーの値）
- 名前："appid"（API キーのパラメーター名）
- 位置：「クエリパラメーター」（API キーは URL 内にあります）
-
「新しいフィールドグループを追加」をクリックして、API パラメーターセットごとに新しいフィールドグループを追加します。フィールドグループ名にはスペースや特殊文字を使用しないでください。この例では、各パラメーターセット（都市と経度／緯度）ごとに 1 つずつ、2 つのフィールドグループを作成する必要があります。
「long/lat」パラメーターセットの場合、次の情報を含むフィールドグループを作成します。
- 使用場所：フィールドグループを使用するジャーニーの数を表示します。ジャーニーを表示 アイコンをクリックし、このフィールドグループを使用するジャーニーのリストを表示できます。
- メソッド：POST または GET メソッドを選択します。この場合は、GET メソッドを選択します。
- 応答ペイロード：ペイロード フィールド内でクリックし、呼び出しによって返されたペイロードの例をペーストします。この例では、天気 API の web サイトにあるペイロードを使用しました。フィールドタイプが正しいことを確認します。API が呼び出されるたびに、ペイロードの例に含まれるすべてのフィールドが取得されます。現在渡されているペイロードを変更する場合、「新しいペイロードをペースト」をクリックします。
- 動的な値：この例では、「long,lat」というコンマで区切られた異なるパラメーターを入力します。パラメーター値は実行コンテキストに依存するので、ジャーニーで定義されます。このページを参照してください。
- 送信済みペイロード：このフィールドは、この例では表示されません。POST メソッドを選択した場合にのみ使用できます。サードパーティシステムに送信されるペイロードをペーストします。
GET 呼び出しにパラメーターが必要な場合は、「 動的な値」フィールドにパラメーターを入力すると、呼び出しの最後に自動的に追加されます。POST 呼び出しの場合は、次の操作が必要です。
-
呼び出し時に渡すパラメーターを「動的な値」フィールドにリストします（以下の例では「identifier」）。
-
また、送信済みペイロードの本文で同じ構文を使用して指定します。そのためには、「"param": "パラメーター名"」（以下の例ではパラメーター名は「identifier」）を追加する必要があります。次の構文に従います。
code language-none {"id":{"param":"identifier"}}
「保存」をクリックします。
これで、データソースが設定され、ジャーニーで使用できる状態になりました。これで、状況に応じて、メールをパーソナライズできます。温度が 30°C を超える場合、特定のコミュニケーションを送信するようにできます。
カスタム認証モード section_wjp_nl5_nhb
この認証モードは、複雑な認証に使用され、OAuth2 などの API ラッピングプロトコルを呼び出すために頻繁に使用されます。これにより、アクションの実際の HTTP リクエストに挿入するアクセストークンが取得されます。
カスタム認証を設定する場合は、下のボタンをクリックして、カスタム認証ペイロードが正しく設定されているかどうかを確認できます。
テストに成功すると、ボタンが緑色に変わります。
この認証では、アクションの実行は次の 2 つの手順で構成されます。
- エンドポイントを呼び出して、アクセストークンを生成します。
- アクセストークンを適切な方法で挿入して、REST API を呼び出します。
この認証には 2 つの部分があります。
アクセストークンの生成時に呼び出されるエンドポイントの定義：
-
endpoint：エンドポイントの生成に使用する URL
-
エンドポイントでの HTTP リクエストのメソッド（GET または POST）
-
headers：必要に応じて、この呼び出しでヘッダーとして挿入されるキーと値のペア。
-
body：メソッドが POST の場合の呼び出しの本文を記述します。bodyParams（キーと値のペア）で定義される、制限付きの本文構造をサポートしています。bodyType は、呼び出しでの本文の形式とエンコーディングを記述します。
- 'form'：コンテンツタイプは application/x-www-form-urlencoded（文字セット UTF-8）になり、キーと値のペアは key1=value1&key2=value2&… のようにシリアル化されます。
- 'json'：コンテンツタイプは application/json（文字セット UTF-8）になり、キーと値のペアは { "key1": "value1", "key2": "value2", …} のように json オブジェクトとしてシリアル化されます。
アクションの HTTP リクエストにアクセストークンを挿入する方法の定義：
-
authorizationType：生成されたアクセストークンをアクションの HTTP 呼び出しに挿入する方法を定義します。使用可能な値は次のとおりです。
- bearer：Authorization: Bearer <access token> のように、アクセストークンを Authorization ヘッダーに挿入する必要があることを示します。
- header：プロパティ tokenTarget で定義されたヘッダー名のヘッダーとして、アクセストークンを挿入する必要があることを示しています。例えば、tokenTarget が myHeader の場合、アクセストークンは myHeader: <access token> のようにヘッダーとして挿入されます。
- queryParam：プロパティ tokenTarget で定義されたクエリパラメーター名である queryParam として、アクセストークンを挿入する必要があることを示します。例えば、tokenTarget が myQueryParam の場合、アクション呼び出しの URL は <url>?myQueryParam=<access token> のようになります。
-
tokenInResponse：認証呼び出しからアクセストークンを抽出する方法を示します。このプロパティには次のようなものがあります。
- 'response'：HTTP 応答がアクセストークンであることを示します
- JSON 内のセレクター（応答が JSON であると仮定し、XML などの他の形式はサポートされません）。このセレクターの形式は json://<path to the access token property> です。例えば、呼び出しの応答が { "access_token": "theToken", "timestamp": 12323445656 } の場合、tokenInResponse は json: //access_token のようになります。
この認証の形式は次のとおりです。
{
"type": "customAuthorization",
"authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
(optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
"endpoint": "<URL of the authentication endpoint>",
"method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
(optional) "headers": {
"<header name>": "<header value>",
...
},
(optional, mandatory if method is 'POST') "body": {
"bodyType": "<'form'or 'json'>,
"bodyParams": {
"param1": value1,
...
}
},
"tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'"
}
カスタム認証データソース用のトークンのキャッシュ時間を変更できます。次に、カスタム認証ペイロードの例を示します。キャッシュ時間は、「cacheDuration」パラメーターで定義します。キャッシュ内の生成されたトークンの保持期間を指定します。単位はミリ秒、秒、分、時間、日、月、年です。
"authentication": {
"type":"customAuthorization",
"authorizationType":"Bearer",
"endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
"method":"POST",
"headers": {
"Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
},
"body": {
"bodyType":"form",
"bodyParams": {
"scope":"cn mail givenname uid employeeNumber",
"grant_type":"password",
"username":"${epsilonUserName}",
"password":"${epsilonUserPassword}"
}
},
"tokenInResponse":"json://access_token",
"cacheDuration":
{ "duration":5, "timeUnit":"seconds" }
}