HTTP API 接続

概要

重要

この宛先は次の場所でのみ使用できます: Real-time Customer Data Platform Ultimate 顧客。

HTTP API の宛先は Adobe Experience Platform プロファイルデータをサードパーティの HTTP エンドポイントに送信する際に役立つストリーミングの宛先です。

プロファイルデータを HTTP エンドポイントに送信するには、まず 宛先に接続 in Adobe Experience Platform.

ユースケース

HTTP API の宛先を使用すると、XDM プロファイルデータとオーディエンスセグメントを汎用の HTTP エンドポイントに書き出すことができます。 ここでは、独自の分析を実行したり、Experience Platformからエクスポートされたプロファイルデータに対して必要なその他の操作を実行したりできます。

HTTP エンドポイントは、お客様独自のシステムまたはサードパーティのソリューションのいずれかになります。

エクスポートのタイプと頻度

宛先の書き出しのタイプと頻度について詳しくは、次の表を参照してください。

項目 タイプ 備考
書き出しタイプ プロファイルベース セグメントのすべてのメンバーを、目的のスキーマフィールド ( 例:電子メールアドレス、電話番号、姓 )。 宛先のアクティベーションワークフロー.
書き出し頻度 ストリーミング ストリーミングの宛先は、API ベースの接続です。 セグメント評価に基づいてExperience Platform内でプロファイルが更新されるとすぐに、コネクタは更新を宛先プラットフォームに送信します。 詳細を表示 ストリーミング先.

前提条件

HTTP API の宛先を使用してExperience Platformからデータを書き出すには、次の前提条件を満たす必要があります。

  • REST API をサポートする HTTP エンドポイントが必要です。
  • HTTP エンドポイントは、Experience Platformプロファイルスキーマをサポートする必要があります。 HTTP API の宛先では、サードパーティのペイロードスキーマへの変換はサポートされていません。 詳しくは、 書き出されたデータ 「 」セクションに、Experience Platform出力スキーマの例を示します。
  • HTTP エンドポイントはヘッダーをサポートする必要があります。
ヒント

また、 Adobe Experience Platform Destination SDK :統合を設定し、HTTP エンドポイントにExperience Platformプロファイルデータを送信します。

IP アドレスの許可リスト

お客様のセキュリティおよびコンプライアンス要件を満たすために、Experience Platformは HTTP API 宛先に対してできる静的 IP のリストを提供しま許可リストす。 参照: ストリーミング先の IP アドレス許可リスト :する IP の完全なリストを表示しま許可リストす。

サポートしている認証タイプ

HTTP API の宛先は、HTTP エンドポイントに対して複数の認証タイプをサポートします。

  • 認証のない HTTP エンドポイント。
  • Bearer トークン認証
  • OAuth 2.0 クライアント資格情報 本文形式での認証 client ID, client secret および grant type を HTTP リクエストの本文に追加します。
curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

宛先への接続

重要

宛先に接続するには、 宛先の管理 アクセス制御権限. 詳しくは、 アクセス制御の概要 または製品管理者に問い合わせて、必要な権限を取得してください。

この宛先に接続するには、宛先設定のチュートリアルの手順に従ってください。この宛先に接続する際は、次の情報を指定する必要があります。

認証情報

Bearer トークン認証

次を選択した場合、 Bearer トークン HTTP エンドポイントに接続するための認証タイプ。以下のフィールドを入力し、「 」を選択します。 宛先に接続:

bearer トークン認証を使用して HTTP API の宛先に接続できる UI 画面の画像

  • Bearer トークン:bearer トークンを挿入して、HTTP ロケーションに対する認証をおこないます。

認証なし

次を選択した場合、 なし HTTP エンドポイントに接続するための認証タイプ:

認証なしで HTTP API の宛先に接続できる UI 画面の画像

この認証を開いた状態で選択する場合は、 宛先に接続 およびは、エンドポイントへの接続を確立します。

OAuth 2 パスワード認証

次を選択した場合、 OAuth 2 パスワード HTTP エンドポイントに接続するための認証タイプ。以下のフィールドを入力し、「 」を選択します。 宛先に接続:

パスワード認証を使用して OAuth 2 を使用し、HTTP API の宛先に接続できる UI 画面の画像

  • トークン URL にアクセス:ユーザー側の URL で、トークンにアクセスし、必要に応じて更新トークンを発行します。
  • クライアント ID:この client ID システムがAdobe Experience Platformに割り当てる
  • クライアント秘密鍵:この client secret システムがAdobe Experience Platformに割り当てる
  • ユーザー名:HTTP エンドポイントにアクセスするユーザー名。
  • パスワード:HTTP エンドポイントにアクセスするためのパスワード。

OAuth 2 クライアント資格情報認証

次を選択した場合、 OAuth 2 クライアント資格情報 HTTP エンドポイントに接続するための認証タイプ。以下のフィールドを入力し、「 」を選択します。 宛先に接続:

クライアント資格情報認証で OAuth 2 を使用して HTTP API 宛先に接続できる UI 画面の画像

  • トークン URL にアクセス:ユーザー側の URL で、トークンにアクセスし、必要に応じて更新トークンを発行します。
  • クライアント ID:この client ID システムがAdobe Experience Platformに割り当てる
  • クライアント秘密鍵:この client secret システムがAdobe Experience Platformに割り当てる
  • クライアント資格情報の種類:お使いのエンドポイントでサポートされる OAuth2 クライアント資格情報付与のタイプを選択します。
    • 本文のエンコード:この場合、 client ID および client secret 含まれる リクエストの本文内 を宛先に送信しました。 例については、 サポートされる認証タイプ 」セクションに入力します。
    • 基本認証:この場合、 client ID および client secret 含まれる Authorization ヘッダー base64 エンコードされ、宛先に送信された後。 例については、 サポートされる認証タイプ 」セクションに入力します。

宛先の詳細を入力

宛先の詳細を設定するには、以下の必須フィールドとオプションフィールドに入力します。 UI でフィールドの横にアスタリスクが表示される場合は、そのフィールドが必須であることを示します。

HTTP 宛先の詳細に関する入力済みフィールドを示す UI 画面の画像

  • 名前:この宛先が将来認識される名前を入力します。
  • 説明:今後この宛先を識別するのに役立つ説明を入力します。
  • ヘッダー:宛先の呼び出しに含めるカスタムヘッダーを、次の形式で入力します。 header1:value1,header2:value2,...headerN:valueN.
  • HTTP エンドポイント:プロファイルデータの送信先の HTTP エンドポイントの URL。
  • クエリパラメーター:オプションで、HTTP エンドポイント URL にクエリパラメーターを追加できます。 使用するクエリパラメーターを次のように書式設定します。 parameter1=value&parameter2=value.
  • セグメント名を含める:データの書き出しで、書き出すセグメントの名前を含めるかどうかを切り替えます。 このオプションを選択した場合のデータエクスポートの例については、 書き出されたデータ の節を参照してください。
  • セグメントのタイムスタンプを含める:セグメントが作成および更新された際の UNIX タイムスタンプと、セグメントがアクティベーションのために宛先にマッピングされた際の UNIX タイムスタンプをデータエクスポートに含めるかどうかを切り替えます。 このオプションを選択した場合のデータエクスポートの例については、 書き出されたデータ の節を参照してください。

アラートの有効化

アラートを有効にして、宛先へのデータフローのステータスに関する通知を受け取ることができます。 リストからアラートを選択して、データフローのステータスに関する通知を受け取るよう登録します。アラートの詳細については、 UI を使用した宛先アラートの購読.

宛先接続の詳細の指定が完了したら、 次へ.

この宛先に対してセグメントをアクティブ化

重要

データをアクティブ化するには、 宛先の管理, 宛先のアクティブ化, プロファイルの表示、および セグメントを表示 アクセス制御権限. 詳しくは、 アクセス制御の概要 または製品管理者に問い合わせて、必要な権限を取得してください。

詳しくは、 ストリーミングプロファイルの書き出し先に対するオーディエンスデータのアクティブ化 を参照してください。

宛先属性

属性を選択 手順に従い、Adobeでは、 和集合スキーマ. 宛先に書き出す一意の ID およびその他の XDM フィールドを選択します。

プロファイルの書き出し動作

Experience Platformは、セグメント認定または他の重要なイベントに続いてプロファイルに関連する更新が発生した場合にのみ、HTTP API 宛先へのプロファイルの書き出し動作を最適化します。 プロファイルは、次の状況で宛先に書き出されます。

  • プロファイルの更新は、宛先にマッピングされた少なくとも 1 つのセグメントのセグメントメンバーシップの変更によって決定されました。 例えば、プロファイルは、宛先にマッピングされたいずれかのセグメントに適合しているか、宛先にマッピングされたいずれかのセグメントから退出しています。
  • プロファイルの更新は、 id マップ. 例えば、宛先にマッピングされたセグメントの 1 つに対して既に適合しているプロファイルの ID マップ属性に新しい ID が追加されたとします。
  • プロファイルの更新は、宛先にマッピングされた属性の少なくとも 1 つに対する属性の変更によって決定されました。 例えば、マッピング手順で宛先にマッピングされた属性の 1 つがプロファイルに追加されます。

上記のすべての場合、関連する更新がおこなわれたプロファイルのみが宛先にエクスポートされます。 例えば、宛先フローにマッピングされたセグメントのメンバーが 100 人で、5 つの新しいプロファイルがセグメントの対象として認定されている場合、宛先への書き出しは増分で、5 つの新しいプロファイルのみが含まれます。

変更内容がどこにあっても、プロファイルに対してマッピングされたすべての属性が書き出されることに注意してください。 したがって、上の例では、属性自体が変更されていない場合でも、これら 5 つの新しいプロファイルに対してマッピングされたすべての属性が書き出されます。

何がデータエクスポートを決定し、何がエクスポートに含まれるか

特定のプロファイルに対して書き出されるデータに関しては、 は、HTTP API 宛先へのデータ書き出しを決定するものです。 および エクスポートに含まれるデータ.

宛先の書き出しを決定する要素 宛先の書き出しに含まれる内容
  • マッピングされた属性とセグメントは、宛先の書き出しのキューとして機能します。 つまり、マッピングされたセグメントの状態(null から適合済み、適合済み/既存から既存へ)が変更されたり、マッピングされた属性が更新された場合、宛先の書き出しがキックオフされます。
  • ID は現在 HTTP API の宛先にマッピングできないので、特定のプロファイルの ID の変更によって宛先の書き出しも決まります。
  • 属性に対する変更は、同じ値であるかどうかに関わらず、属性に対する更新として定義されます。 つまり、値自体が変更されていない場合でも、属性の上書きは変更と見なされます。
  • (最新のメンバーシップステータスを持つ)すべてのセグメントは、データフローにマッピングされているかどうかに関係なく、 segmentMembership オブジェクト。
  • 内のすべての ID identityMap オブジェクトも含まれます (Experience Platformは、現在、HTTP API の宛先で ID マッピングをサポートしていません )。
  • マッピングされた属性のみが宛先エクスポートに含まれます。

例えば、このデータフローを HTTP 宛先に対して考えてみましょう。この宛先では、3 つのセグメントがデータフローで選択され、4 つの属性が宛先にマッピングされます。

HTTP API 宛先のデータフロー

宛先へのプロファイルエクスポートは、いずれかの 3 つのマッピングされたセグメント. ただし、データエクスポートでは、 segmentMembership オブジェクト ( 書き出されたデータ の節を参照 )、その特定のプロファイルがそのメンバーの場合は、その他のマッピングされていないセグメントが表示されることがあります。 プロファイルが DeLorean Cars セグメントで顧客の資格を得ている一方で、「Back to the Future」映画や SF ファンセグメントのメンバーでもある場合、他の 2 つのセグメントも segmentMembership データエクスポートのオブジェクト(データフローでマッピングされていない場合)。

プロファイル属性の観点から、上でマッピングした 4 つの属性に対する変更によって、書き出し先が決まり、プロファイルに存在する 4 つのマッピング済み属性のいずれかがデータ書き出しに表示されます。

履歴データのバックフィル

新しいセグメントを既存の宛先に追加する場合、または新しい宛先を作成してセグメントをマッピングする場合、Experience Platformは宛先にセグメントの資格情報の履歴データをエクスポートします。 セグメントに適合するプロファイル セグメントが宛先に追加され、約 1 時間以内に宛先に書き出されます。

書き出したデータ

エクスポート済み Experience Platform データは、 HTTP の宛先を JSON 形式で指定します。 例えば、以下のエクスポートには、特定のセグメントに適合し、別の 2 つのセグメントのメンバーであり、別のセグメントから離脱したプロファイルが含まれています。 書き出しには、プロファイル属性の名、姓、生年月日、個人の電子メールアドレスも含まれます。 このプロファイルの ID は、ECID と電子メールです。

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"existing"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"existing"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

次に、 セグメント名を含める および セグメントのタイムスタンプを含める options:

 以下のデータエクスポートのサンプルでは、 segmentMembership セクション
"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }
 以下のデータエクスポートの例では、 segmentMembership セクション
"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

制限および再試行ポリシー

95%の確率で、Experience Platformは、各データフローから HTTP 宛先への各リクエストの 1 秒あたり 10,000 リクエスト未満の割合で正常に送信されたメッセージに対して、10 分未満のスループット遅延を提供しようとします。

HTTP API 宛先へのリクエストが失敗した場合、Experience Platformは失敗したリクエストを保存し、リクエストをエンドポイントに送信するために 2 回再試行します。

このページ