外部データソース external-data-sources

外部データソースを使用すると、サードパーティシステムへの接続を定義できます。例えば、ホテルの予約システムを使用して、部屋が登録されたかどうかを確認する場合などです。組み込みの Adobe Experience Platform データソースとは異なり、外部データソースは必要な分だけ作成できます。

NOTE
外部システムを操作する際のガードレールについては、このページを参照してください。
NOTE
応答がサポートされるようになったので、外部データソースのユースケースでは、データソースの代わりにカスタムアクションを使用する必要があります。応答について詳しくは、このを参照してください。

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)が含まれます。

新しい外部データソースを作成して構成するための主な手順は次のとおりです。

  1. データソースのリストで「データソースを作成」をクリックして、新しい外部データソースを作成します。

    画面の右側にデータソース設定ペインが開きます。

  2. データソースの名前を入力します。

    note note
    NOTE
    英数字とアンダースコアのみが使用できます。最大長は 30 文字です。
  3. データソースに説明を追加します。この手順はオプションです。

  4. 外部サービスの URL を追加します。この例では、次のようになります。https://api.adobeweather.org/weather

    note caution
    CAUTION
    セキュリティ上の理由から、HTTPS の使用を強くお勧めします。また、アドビの非公開アドレスや IP アドレスの使用は許可されていません。

  5. 外部サービスの設定に応じて認証を​ 認証なし基本カスタム ​または API キー ​に設定します。

    基本認証モードの場合は、ユーザー名とパスワードを入力する必要があります。

    note note
    NOTE
    認証呼び出しを実行すると、base64 でエンコードされた <username>:<password> 文字列が認証ヘッダーに追加されます。

    カスタム認証モードについて詳しくは、この節を参照してください。この例では、API キー認証モードを選択します。

    • タイプ:API キー
    • 名前:"appid"(API キーのパラメーター名)
    • :"1234"(API キーの値)
    • 位置:「クエリパラメーター」(API キーは URL 内にあります)

  6. 新しいフィールドグループを追加」をクリックして、API パラメーターセットごとに新しいフィールドグループを追加します。フィールドグループ名には、英数字とアンダースコアのみを使用できます。最大長は 30 文字です。この例では、各パラメーターセット(都市と経度/緯度)ごとに 1 つずつ、2 つのフィールドグループを作成する必要があります。

「long/lat」パラメーターセットの場合、次の情報を含むフィールドグループを作成します。

  • 使用場所:フィールドグループを使用するジャーニーの数を表示します。ジャーニーを表示 ​アイコンをクリックし、このフィールドグループを使用するジャーニーのリストを表示できます。

  • メソッド:POST または GET メソッドを選択します。この場合は、GET メソッドを選択します。

  • 動的な値:この例では、「long,lat」というコンマで区切られた異なるパラメーターを入力します。パラメーター値は実行コンテキストに依存するので、ジャーニーで定義されます。詳細情報

  • 応答ペイロードペイロード ​フィールド内でクリックし、呼び出しによって返されたペイロードの例をペーストします。この例では、天気 API の web サイトにあるペイロードを使用しました。フィールドタイプが正しいことを確認します。API が呼び出されるたびに、ペイロードの例に含まれるすべてのフィールドが取得されます。現在渡されているペイロードを変更する場合、「新しいペイロードをペースト」をクリックします。

  • 送信済みペイロード:このフィールドは、この例では表示されません。POST メソッドを選択した場合にのみ使用できます。サードパーティシステムに送信されるペイロードをペーストします。

GET 呼び出しにパラメーターが必要な場合は、「 動的な値」フィールドにパラメーターを入力すると、呼び出しの最後に自動的に追加されます。POST 呼び出しの場合は、次の操作が必要です。

  • 呼び出し時に渡すパラメーターを「動的な値」フィールドにリストします(以下の例では「identifier」)。

  • また、送信済みペイロードの本文で同じ構文を使用して指定します。そのためには、「"param": "パラメーター名"」(以下の例では「identifier」)を追加する必要があります。次の構文に従います。

    code language-json
    {"id":{"param":"identifier"}}
    

保存」をクリックします。

これで、データソースが設定され、ジャーニーで使用できる状態になりました。これで、状況に応じて、メールをパーソナライズできます。温度が 30°C を超える場合、特定のコミュニケーションを送信するようにできます。

カスタム認証モード custom-authentication-mode

この認証モードは、複雑な認証に使用され、OAuth2 などの API ラッピングプロトコルを呼び出すために頻繁に使用されます。これにより、アクションの実際の HTTP リクエストに挿入するアクセストークンが取得されます。

カスタム認証を設定する場合は、下のボタンをクリックして、カスタム認証ペイロードが正しく設定されているかどうかを確認できます。

テストに成功すると、ボタンが緑色に変わります。

この認証では、アクションの実行は次の 2 つの手順で構成されます。

  1. エンドポイントを呼び出して、アクセストークンを生成します。
  2. アクセストークンを適切な方法で挿入して、REST API を呼び出します。
NOTE
この認証には 2 つの部分があります。

アクセストークンの生成時に呼び出されるエンドポイントの定義 custom-authentication-endpoint

  • 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)で、キーと値のペアが JSON オブジェクトとして { "key1": "value1", "key2": "value2", …} のようにシリアル化されることを意味します。

アクションの HTTP リクエストにアクセストークンを挿入する方法の定義 custom-authentication-access-token

  • authorizationType:生成されたアクセストークンをアクションの HTTP 呼び出しに挿入する方法を定義します。使用可能な値は次のとおりです。

    • bearerAuthorization: Bearer <access token> のように、アクセストークンを Authorization ヘッダーに挿入する必要があることを示します。
    • header:プロパティ tokenTarget で定義されたヘッダー名のヘッダーとして、アクセストークンを挿入する必要があることを示します。例えば、tokenTargetmyHeader の場合、アクセストークンは 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",
    "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": {
        (optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
        (optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
        "timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
    },
    "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'>",
}
NOTE
Encode64 は、認証ペイロードで使用できる唯一の関数です。

カスタム認証データソース用のトークンのキャッシュ時間を変更できます。次に、カスタム認証ペイロードの例を示します。キャッシュ時間は、cacheDuration パラメーターで定義されます。キャッシュ内の生成されたトークンの保持期間を指定します。単位はミリ秒、秒、分、時間、日、月、年です。

Bearer 認証タイプの例を次に示します。

{
    "type": "customAuthorization",
    "endpoint": "https://<your_auth_endpoint>/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"
    },
  },
NOTE
認証トークンは、ジャーニーごとにキャッシュされます。2 つのジャーニーが同じカスタムアクションを使用している場合、それぞれのジャーニーに独自のトークンがキャッシュされます。そのトークンは、これらのジャーニー間で共有されません。
キャッシュ時間を使用すると、認証エンドポイントへの呼び出しが多くなりすぎないようにすることができます。認証トークンの保持はサービスにキャッシュされ、永続性はありません。サービスを再起動した場合は、キャッシュがクリーンアップされた状態でサービスが開始されます。デフォルトのキャッシュ時間は 1 時間です。カスタム認証ペイロードでは、別の保持時間を指定することで調整することができます。

ヘッダー認証タイプの例を次に示します。

{
  "type": "customAuthorization",
  "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",
  "cacheDuration": {
    "expiryInResponse": "json://expiryDuration",
    "timeUnit": "minutes"
  },
  "authorizationType": "header",
  "tokenTarget": "x-auth-token"
}

ログイン API 呼び出しの応答の例を次に示します。

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
  "expiryDuration" : 5
}
recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76