外部データソース

外部データソースを使用すると、サードパーティシステムへの接続を定義できます。例えば、ホテルの予約システムを使用して、部屋が登録されたかどうかを確認する場合などです。組み込みの 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）で構成されます。

新しい外部データソースを作成および設定する主な手順は次のとおりです。

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

   

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

   

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

   メモ

   スペースや特殊文字は使用しないでください。30 文字以内にしてください。

3. データソースに説明を追加します。この手順はオプションです。

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

   注意

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

   

5. 外部サービスの設定に応じて認証を​認証なし、基本、カスタム、API キー​のいずれかに設定します。カスタム認証モードについて詳しくは、この節を参照してください。この例では、次を選択します。

   • タイプ：API キー
   • 名前："appid"（API キーのパラメーター名）
   • 値："1234"（API キーの値）
   • 場所：クエリパラメーター（API キーは URL 内にあります）

   

6. 「新しいフィールドグループを追加」をクリックして、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 つの手順で構成されるプロセスになります。

1. エンドポイントを呼び出してアクセストークンを生成します。
2. アクセストークンを適切に挿入して REST API を呼び出します。

この認証には 2 つの部分があります。

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

• endpoint：エンドポイントの生成に使用する URL。
• method：エンドポイントでの 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 リクエストにアクセストークンを挿入する方法の定義：

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

  • bearer：アクセストークンを認証ヘッダーに挿入する必要があることを示します（Authorization: Bearer <アクセストークン>）。
  • header：アクセストークンをヘッダーとして挿入する必要があることを示します。ヘッダー名は、tokenTarget プロパティで定義されます。例えば、tokenTarget が myHeader の場合、アクセストークンは myHeader: <アクセストークン>​のようにヘッダーとして挿入されます。
  • queryParam：アクセストークンを queryParam（プロパティ tokenTarget で定義されるクエリパラメーター名）として挿入する必要があることを示します。例えば、tokenTarget が myQueryParam の場合、アクション呼び出しの URL は <url>?myQueryParam=<アクセストークン> のようになります。

• tokenInResponse：認証呼び出しからアクセストークンを抽出する方法を示します。このプロパティは次のいずれかになります。

  • 'response'：HTTP 応答がアクセストークンであることを示します。
  • json のセレクター（応答が json である場合、XML などの他の形式はサポートされません）。このセレクターの形式は、json://<アクセストークンプロパティのパス>​です。例えば、呼び出しの応答が { "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」パラメーターで定義されます。キャッシュ内で生成されたトークンの保存期間を指定します。単位は、ミリ秒、秒、分、時間、日、月、年です。

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"
    }
  }
}

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

{
  "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"
}