[Ultimate]{class="badge positive"}

HTTP API 接続

概要 overview

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

プロファイルデータをHTTP エンドポイントに送信するには、まずExperience Platformの宛先に接続する必要があります。

ユースケース use-cases

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

HTTP エンドポイントとして設定できるのは、顧客独自のシステムまたはサードパーティソリューションのいずれかです。

サポートされるオーディエンス supported-audiences

この節では、この宛先に書き出すことができるオーディエンスのタイプについて説明します。

オーディエンスのデータタイプ別にサポートされるオーディエンス：

書き出しのタイプと頻度 export-type-frequency

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

前提条件 prerequisites

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

mTLS プロトコルのサポートと証明書 mtls-protocol-support

Mutual Transport Layer Security （mTLS）を使用して、HTTP API宛先接続へのアウトバウンド接続のセキュリティを強化できます。

mTLSは、情報を共有する両当事者が、データを共有する前に誰であると主張するかを保証する相互認証プロトコルです。 mTLSには、標準のTLSと比較した追加の手順が含まれており、サーバーはクライアントの証明書を要求および検証し、クライアントはサーバーの証明書を検証します。

mTLSの考慮事項 mtls-considerations

HTTP API宛先に対するmTLS サポートは、プロファイルの書き出しが送信されるデータ受信エンドポイント にのみ​適用されます（HTTP Endpoint​宛先の詳細の フィールド）。

データ書き出し用のmTLSの設定 configuring-mtls

HTTP API宛先でmTLSを使用するには、HTTP Endpoint​宛先の詳細​ ページで設定する （データ受信エンドポイント）でTLS プロトコルを無効にし、mTLSのみを有効にする必要があります。 エンドポイントで引き続きTLS 1.2 プロトコルが有効になっている場合、クライアント認証用の証明書は送信されません。 つまり、HTTP API宛先でmTLSを使用するには、データ受信サーバーエンドポイントがmTLS専用に有効な接続エンドポイントである必要があります。

証明書の詳細の取得と検査 certificate

Common Name （CN）やSubject Alternative Names （SAN）などの証明書の詳細を検査してサードパーティによる検証を追加する場合は、APIを使用して証明書を取得し、応答からこれらのフィールドを抽出します。

詳しくは、公開証明書エンドポイントのドキュメント ​を参照してください。

IP アドレスの許可リスト ip-address-allowlist

顧客のセキュリティおよびコンプライアンスの要件を満たすために、Experience Platform には HTTP API 宛先の許可リストに使用できる静的 IP のリストが用意されています。許可リストに加えるするIPの完全なリストについては、​ ストリーミング宛先のIP アドレスの許可リストに加えるを参照してください。

サポートしている認証タイプ supported-authentication-types

HTTP API 宛先は、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'

宛先への接続 connect-destination

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

認証情報 authentication-information

ベアラートークン認証 bearer-token-authentication

HTTP エンドポイントに接続する​ Bearer token ​認証タイプを選択した場合は、以下の情報を入力し、Connect to destination​を選択します。

認証なし no-authentication

HTTP エンドポイントに接続する​ None ​認証タイプを選択した場合：

この認証オプションを選択すると、Connect to destination​を選択するだけで、エンドポイントへの接続が確立されます。

OAuth 2 パスワード認証 oauth-2-password-authentication

HTTP エンドポイントに接続する​ OAuth 2 Password ​認証タイプを選択した場合は、以下の情報を入力し、Connect to destination​を選択します。

OAuth 2 クライアント資格情報認証 oauth-2-client-credentials-authentication

HTTP エンドポイントに接続する​ OAuth 2 Client Credentials ​認証タイプを選択した場合は、以下の情報を入力し、Connect to destination​を選択します。

宛先の詳細を入力 destination-details

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

アラートの有効化 enable-alerts

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

宛先接続の詳細の提供が完了したら、Next​を選択します。

この宛先に対してオーディエンスをアクティブ化 activate

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

宛先属性 attributes

Select attributes ステップでは、Adobeは結合スキーマ ​から一意のIDを選択することをお勧めします。 宛先に書き出す一意の ID およびその他の XDM フィールドを選択します。

プロファイルの書き出し動作 profile-export-behavior

Experience Platformは、プロファイルの書き出し動作をHTTP API宛先に最適化し、オーディエンスの選定やその他の重要なイベントの後にプロファイルに関連する更新が発生した場合にのみ、データをAPI エンドポイントに書き出します。 プロファイルは、以下の状況で宛先に書き出されます。

上記のすべての場合で、適切な更新が行われたプロファイルのみが宛先に書き出されます。例えば、宛先フローにマッピングされたオーディエンスに100人のメンバーがあり、5つの新しいプロファイルがオーディエンスに適格である場合、宛先への書き出しは増分であり、5つの新しいプロファイルのみが含まれます。

データの書き出しを決定する要素と、書き出しに含まれる内容 what-determines-export-what-is-included

特定のプロファイルに対して書き出されるデータに関しては、HTTP API 宛先へのデータ書き出しを決定する要素、および​ 書き出しに含まれるデータ ​という 2 つの異なる概念を理解することが重要です。

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

宛先へのプロファイル書き出しは、プロファイルが​ 3つのマッピングされたオーディエンス ​のいずれかに適格または離脱したときにトリガーされます。 データの書き出しでは、そのプロファイルがそのメンバーであり、書き出しをトリガーしたオーディエンスと同じ結合ポリシーを共有している場合、segmentMembership オブジェクト（以下の書き出されたデータ ​を参照）にマッピングされていないオーディエンスも含めることができます。 例えば、プロファイルが​ Customer with DeLorean Cars ​のオーディエンスに適格でありながら、視聴した「Back to the Future」​映画と​ Sf ファン ​のオーディエンスのメンバーでもある場合、これらの2つのオーディエンスはsegmentMembership オブジェクトにも表示されます。ただし、これらの2つのオーディエンスが​ Customer with DeLorean Cars ​のオーディエンスと同じ結合ポリシーを共有している場合です。

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

履歴データのバックフィル historical-data-backfill

既存の宛先に新しいオーディエンスを追加する場合、または新しい宛先を作成してオーディエンスをマッピングする場合、Experience Platformは過去のオーディエンスの選定データを宛先に書き出します。 オーディエンスが宛先に追加された​ 前 ​のオーディエンスに適格なプロファイルは、約1時間以内に宛先に書き出されます。

書き出したデータ exported-data

書き出されたExperience Platform データは、JSON形式でHTTP宛先に格納されます。 例えば、以下の書き出しには、特定のオーディエンスに適合し、別の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":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "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"
      }
    ]
  }
}

Include Segment Names​および​Include Segment Timestamps オプションの接続先フローで選択したUI設定に応じて、書き出されたデータの詳細な例を次に示します。

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000
          }
        }
      }

制限と再試行ポリシー limits-retry-policy

Experience Platformでは、95%の確率で、HTTP宛先への各データフローに対して1秒間に10千回未満のリクエストを送信した場合、スループット待ち時間を10分未満に抑えようとします。

HTTP API宛先へのリクエストが失敗した場合、Experience Platformはそれらを保存し、2回再試行します。

トラブルシューティング troubleshooting

信頼性の高いデータ配信を確保し、タイムアウトの問題を回避するには、前提条件 セクションで指定されているように、HTTP エンドポイントがExperience Platform リクエストに2秒以内に応答することを確認します。 応答に時間がかかると、タイムアウトエラーが発生します。