外部データソースを使用すると、サードパーティシステムへの接続を定義できます。例えば、ホテルの予約システムを使用して、部屋が登録されたかどうかを確認する場合などです。組み込みの Adobe Experience Platform データソースとは異なり、外部データソースは必要な数だけ作成できます。
外部システムを操作する際のガードレールについては、このページを参照してください。
POST または GET を使用して JSON を返す REST API がサポートされています。API キー認証モード、基本認証モード、カスタム認証モードがサポートされています。
次に、リアルタイムの天気データに従ってジャーニーの行動をカスタマイズするのに使用する天気 API サービスの例を見てみましょう。
API 呼び出しの例を 2 つ示します。
この呼び出しは、メイン URL(https://api.adobeweather.org/weather)、2 つのパラメーターセット(市区町村を表す「city」、緯度と経度を表す「lat/long」)、API キー(appid)で構成されます。
新しい外部データソースを作成および設定する主な手順は次のとおりです。
データソースのリストで「データソースを作成」をクリックして、新しい外部データソースを作成します。
画面の右側にデータソース設定ペインが開きます。
データソースの名前を入力します。
スペースや特殊文字は使用しないでください。30 文字以内にしてください。
データソースに説明を追加します。この手順はオプションです。
外部サービスの URL を追加します。この例では、https://api.adobeweather.org/weather です。
セキュリティ上の理由から、HTTPS の使用を強くお勧めします。また、一般公開されていないアドビのアドレスの使用および IP アドレスの使用は許可されていません。
外部サービスの設定に応じて認証を認証なし、基本、カスタム、API キーのいずれかに設定します。カスタム認証モードについて詳しくは、この節を参照してください。この例では、次を選択します。
「新しいフィールドグループを追加」をクリックして、API パラメーターセットごとに新しいフィールドグループを作成します。フィールドグループ名にはスペースや特殊文字を使用しないでください。この例では、パラメーターセット(city と longlat)ごとに 1 つずつ、2 つのフィールドグループを作成する必要があります。
「longlat」パラメーターセットに対して、次の情報を持つフィールドグループを作成します。
使用されている場所:フィールドグループを使用するジャーニーの数を表示します。ジャーニーを表示アイコンをクリックすると、このフィールドグループを使用するジャーニーのリストを表示できます。
メソッド:POST または GET メソッドを選択します。ここでは GET メソッドを選択します。
動的値:この例では、コンマで区切られた異なるパラメーター「long,lat」を入力します。パラメーター値は実行コンテキストに依存するので、ジャーニーで定義されます。詳細情報
応答ペイロード:「ペイロード」フィールド内をクリックし、呼び出しによって返されたペイロードの例を貼り付けます。この例では、天気 API の web サイトで見つかったペイロードを使用しました。フィールドタイプが正しいことを確認します。API が呼び出されるたびに、ペイロードの例に含まれるすべてのフィールドが取得されます。現在渡されているペイロードを変更する場合は、「新しいペイロードを貼り付け」をクリックできます。
送信済みペイロード:このフィールドは、この例では表示されません。このフィールドは POST メソッドを選択した場合にのみ使用できます。サードパーティシステムに送信するペイロードを貼り付けます。
GET 呼び出しにパラメーターが必要な場合は、「 動的な値」フィールドにパラメーターを入力すると、呼び出しの最後に自動的に追加されます。POST 呼び出しの場合は、次の操作が必要です。
呼び出し時に渡すパラメーターを「動的な値」フィールドにリストします(以下の例では「identifier」)。
また、送信済みペイロードの本文で同じ構文を使用して指定します。そのためには、「"param": "パラメーター名"」(以下の例では「identifier」)を追加する必要があります。以下の構文に従います。
{"id":{"param":"identifier"}}
「保存」をクリックします。
これで、データソースが設定され、ジャーニーで使用できる状態になりました。これで、状況に応じて、メールをパーソナライズできます。例えば、気温が 30 ℃を超える場合に特定の通信を送信したりできます。
この認証モードは複雑な認証に使用され、OAuth2 などの API ラッピングプロトコルを呼び出して、アクションの実際の HTTP リクエストに挿入されるアクセストークンを取得するために頻繁に使用されます。
カスタム認証を設定する場合、下のボタンをクリックして、カスタム認証ペイロードが正しく設定されているかどうかを確認できます。
テストが成功すると、ボタンが緑色に変わります。
この認証を使用すると、アクションの実行は次の 2 つの手順で構成されるプロセスになります。
この認証には 2 つの部分があります。
アクセストークンの生成時に呼び出されるエンドポイントの定義:
アクションの HTTP リクエストにアクセストークンを挿入する方法の定義:
authorizationType:生成されたアクセストークンを、アクションの HTTP 呼び出しに挿入する方法を定義します。使用可能な値は次のとおりです。
tokenInResponse:認証呼び出しからアクセストークンを抽出する方法を示します。このプロパティは次のいずれかになります。
この認証の形式は次のとおりです。
{
"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」パラメーターで定義されます。キャッシュ内で生成されたトークンの保存期間を指定します。単位は、ミリ秒、秒、分、時間、日、月、年です。
Bearer 認証タイプの例を次に示します。
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"endpoint": "https://localhost:${port}/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
}
}
}
認証トークンは、ジャーニーごとにキャッシュされます。2 つのジャーニーが同じカスタムアクションを使用している場合、それぞれのジャーニーに独自のトークンがキャッシュされます。そのトークンは、これらのジャーニー間で共有されません。
キャッシュ時間を使用すると、認証エンドポイントへの呼び出しが多くなりすぎないようにすることができます。認証トークンの保持はサービスにキャッシュされ、永続性はありません。サービスを再起動した場合は、キャッシュがクリーンアップされた状態でサービスが開始されます。デフォルトのキャッシュ時間は 1 時間です。カスタム認証ペイロードでは、別の保持時間を指定することで調整することができます。
ヘッダー認証タイプの例を次に示します。
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token"
}
ログイン API 呼び出しの応答の例を次に示します。
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S"
}