[Ultimate]{class="badge positive"}
HTTP API 接続
概要 overview
HTTP API 宛先は、プロファイルデータをサードパーティの HTTP エンドポイントに送信する際に役立つ Adobe Experience Platform ストリーミング宛先です。
プロファイルデータを HTTP エンドポイントに送信するには、まず Adobe Experience Platform で宛先に接続する必要があります。
ユースケース use-cases
HTTP API 宛先を使用すると、XDM プロファイルデータとオーディエンスを汎用の HTTP エンドポイントに書き出すことができます。 そこで、Experience Platform から書き出されたプロファイル データに対して、独自の分析を実行したり、その他の必要な操作を行ったりできます。
HTTP エンドポイントとして設定できるのは、顧客独自のシステムまたはサードパーティソリューションのいずれかです。
サポートされるオーディエンス supported-audiences
この節では、この宛先に書き出すことができるオーディエンスのタイプについて説明します。
書き出しのタイプと頻度 export-type-frequency
宛先の書き出しのタイプと頻度について詳しくは、以下の表を参照してください。
前提条件 prerequisites
Experience Platform からデータを書き出す際に HTTP API 宛先を使用する場合は、次の前提条件を満たす必要があります。
- REST API をサポートする HTTP エンドポイントが必要です。
- 使用する HTTP エンドポイントが、Experience Platform プロファイルスキーマをサポートする必要があります。HTTP API 宛先では、サードパーティのペイロードスキーマへの変換はサポートされていません。Experience Platform の出力スキーマの例については、書き出されたデータの節を参照してください。
- HTTP エンドポイントはヘッダーをサポートする必要があります。
mTLS プロトコルのサポートと証明書 mtls-protocol-support
Mutual Transport Layer Security (mTLS)を使用して、HTTP API 宛先接続へのアウトバウンド接続のセキュリティを強化できます。
mTLS は、相互認証のためのエンドツーエンドのセキュリティ方法であり、情報を共有する両方の関係者が、データが共有される前に本来の姿を保証します。 mTLS には、TLS と比較して、サーバーがクライアントの証明書を要求し、最後に検証する追加の手順が含まれます。
HTTP API の宛先で mTLS を使用する場合は、 宛先の詳細ページに入力するサーバーアドレスで、TLS プロトコルを無効にし、mTLS のみを有効にする必要があります。 エンドポイントで TLS 1.2 プロトコルがまだ有効になっている場合、クライアント認証の証明書は送信されません。 つまり、HTTP API の宛先で mTLS を使用するには、「受信側」サーバーエンドポイントが、mTLS み取り専用で有効な接続エンドポイントである必要があります。
証明書をダウンロード certificate
Common Name (CN)と Subject Alternative Names (SAN)をチェックしてサードパーティの検証を追加する場合は、以下の証明書をダウンロードできます。
また、MTLS エンドポイントにGETリクエストを行うことで、公開証明書を安全に取得できます。 詳しくは、 公開証明書エンドポイントのドキュメントを参照してください。
IP アドレスの許可リスト ip-address-allowlist
顧客のセキュリティおよびコンプライアンスの要件を満たすために、Experience Platform には HTTP API 宛先の許可リストに使用できる静的 IP のリストが用意されています。に許可リストに加える許可リストに加えるされる IP の一覧については、 ストリーミング先の IP アドレスを参照してください。
サポートしている認証タイプ supported-authentication-types
HTTP API 宛先は、HTTP エンドポイントに対して、以下に示す複数の認証タイプをサポートしています。
- 認証なしの HTTP エンドポイント。
- ベアラートークン認証。
- 以下の例に示すように、HTTP リクエストの本文に client ID、client secret、grant type を含み、本文形式を持つ OAuth 2.0 クライアント資格情報認証。
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>'
- URL がエンコードされた client ID および client secret を含む認証ヘッダーを持つ、基本認証による OAuth 2.0 クライアント資格情報。
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 エンドポイントに接続する場合は、以下のフィールドを入力し、「宛先に接続」を選択します。
- ベアラートークン:ベアラートークンを挿入して、HTTP ロケーションに対する認証を行います。
認証なし no-authentication
「なし」の認証タイプを選択して HTTP エンドポイントに接続する場合:
この認証を開いた状態で選択する場合は、「宛先に接続」を選択するだけで、エンドポイントへの接続が確立されます。
OAuth 2 パスワード認証 oauth-2-password-authentication
OAuth 2 パスワード 認証タイプを選択して HTTP エンドポイントに接続する場合は、以下のフィールドを入力し、「宛先に接続」を選択します。
- アクセストークン URL:アクセストークンと必要に応じて更新トークンを発行する、ユーザー側の URL。
- クライアント ID:システムが Adobe Experience Platform に割り当てる client ID。
- クライアント秘密鍵:システムが Adobe Experience Platform に割り当てる client secret。
- ユーザー名:HTTP エンドポイントにアクセスするユーザー名。
- パスワード:HTTP エンドポイントにアクセスするためのパスワード。
OAuth 2 クライアント資格情報認証 oauth-2-client-credentials-authentication
OAuth 2 クライアント資格情報 認証タイプを選択して HTTP エンドポイントに接続する場合は、以下のフィールドを入力し、「宛先に接続」を選択します。
-
アクセストークン URL:アクセストークンと必要に応じて更新トークンを発行する、ユーザー側の URL。
-
クライアント ID:システムが Adobe Experience Platform に割り当てる client ID。
-
クライアント秘密鍵:システムが Adobe Experience Platform に割り当てる client secret。
-
クライアント資格情報の種類:お使いのエンドポイントでサポートされる OAuth2 クライアント資格情報付与の種類を選択します。
- エンコードされた本文:この場合、client ID と client secret は宛先に送信される リクエストの本文 に含まれます。例については、サポートされる認証タイプの節を参照してください。
- 基本認証:この場合、client ID と client secret は、base64 でエンコードして宛先に送信された後、
Authorization
ヘッダー に含まれます。例については、サポートされる認証タイプの節を参照してください。
宛先の詳細を入力 destination-details
宛先の詳細を設定するには、以下の必須フィールドとオプションフィールドに入力します。UI のフィールドの横のアスタリスクは、そのフィールドが必須であることを示します。
- 名前:今後この宛先を認識するための名前を入力します。
- 説明:今後この宛先を識別するのに役立つ説明を入力します。
- ヘッダー:宛先の呼び出しに含めるカスタムヘッダーを、「
header1:value1,header2:value2,...headerN:valueN
」の形式で入力します。 - HTTP エンドポイント:プロファイルデータの送信先の HTTP エンドポイントの URL。
- クエリパラメーター:オプションで、HTTP エンドポイント URL にクエリパラメーターを追加できます。 使用するクエリパラメーターを
parameter1=value¶meter2=value
のように書式設定します。 - セグメント名を含める:書き出すオーディエンスの名前をデータの書き出しに含めるかどうかを切り替えます。 このオプションを選択したデータの書き出しの例については、書き出されたデータの節を参照してください。
- セグメントのタイムスタンプを含める:オーディエンスが作成および更新された際の UNIX タイムスタンプと、アクティブ化のためにオーディエンスが宛先にマッピングされた際の UNIX タイムスタンプをデータの書き出しに含めるかどうかを切り替えます。 このオプションを選択したデータの書き出しの例については、書き出されたデータの節を参照してください。
アラートの有効化 enable-alerts
アラートを有効にすると、宛先へのデータフローのステータスに関する通知を受け取ることができます。リストからアラートを選択して、データフローのステータスに関する通知を受け取るよう登録します。アラートについて詳しくは、UI を使用した宛先アラートの購読についてのガイドを参照してください。
宛先接続の詳細の入力を終えたら「次へ」を選択します。
この宛先に対してオーディエンスをアクティブ化 activate
この宛先にオーディエンスをアクティブ化する手順については、 ストリーミングプロファイル書き出し宛先に対するオーディエンスデータのアクティブ化を参照してください。
宛先属性 attributes
属性を選択の手順では、和集合スキーマから一意の ID を選択することをお勧めします。宛先に書き出す一意の ID およびその他の XDM フィールドを選択します。
プロファイルの書き出し動作 profile-export-behavior
Experience Platformは、オーディエンスの選定または他の重要なイベントに続いてプロファイルに関連する更新が発生した際に API エンドポイントへデータを書き出すためにのみ、HTTP API 宛先へのプロファイルの書き出し動作を最適化します。 プロファイルは、以下の状況で宛先に書き出されます。
- 宛先にマッピングされた 1 つ以上のオーディエンスのオーディエンスメンバーシップの変更によって、プロファイルの更新が決定された場合。 例えば、プロファイルは、宛先にマッピングされたいずれかのオーディエンスに適合しているか、宛先にマッピングされたいずれかのオーディエンスから退出しています。
- プロファイルの更新が、ID マップの変更によって決定する場合。例えば、宛先にマッピングされたオーディエンスの 1 つに対して既に適合しているプロファイルの ID マップ属性に新しい ID が追加されたとします。
- プロファイルの更新は、宛先にマッピングされた属性のうち、少なくとも 1 つの属性が変更されたことで判断されました。例えば、マッピング手順で宛先にマッピングされた属性の 1 つがプロファイルに追加されます。
上記のすべての場合で、適切な更新が行われたプロファイルのみが宛先に書き出されます。例えば、宛先フローにマッピングされたオーディエンスに 100 人のメンバーがいて、5 つの新しいプロファイルがセグメントに適合している場合、宛先への書き出しは増分で行われ、5 つの新しいプロファイルのみが含まれます。
プロファイルについては、変更箇所に関わらず、マッピングされたすべての属性が書き出されることに注意してください。したがって、上の例では、属性自体が変更されていない場合でも、これら 5 つの新しいプロファイルに対してマッピングされた属性がすべて書き出されます。
データの書き出しを決定する要素と、書き出しに含まれる内容 what-determines-export-what-is-included
特定のプロファイルに対して書き出されるデータに関しては、HTTP API 宛先へのデータ書き出しを決定する要素、および 書き出しに含まれるデータ という 2 つの異なる概念を理解することが重要です。
- マッピングされた属性とオーディエンスは、宛先の書き出しのキューとして機能します。つまり、マッピングされたオーディエンスのステータスが(
null
からrealized
に、またはrealized
からexiting
に)変更されたり、マッピングされた属性が更新されたりすると、宛先の書き出しが開始されます。 - ID は現在 HTTP API の宛先にマッピングできないので、特定のプロファイルの ID を変更すると、宛先の書き出しも決定されます。
- 属性の変更は、同じ値であるかどうかに関わらず、属性に対する更新として定義されます。 つまり、値自体が変更されていない場合でも、属性の上書きは変更と見なされます。
segmentMembership
オブジェクトには、アクティブ化データフローでマッピングされたオーディエンスが含まれます。このオーディエンスについて、プロファイルのステータスが選定またはオーディエンス離脱イベントの後に変更されました。なお、これらのオーディエンスが、アクティブ化データフローでマッピングされたオーディエンスと同じ結合ポリシーに属する場合、プロファイルが対象となっていた、他のマッピングされていないオーディエンスを宛先の書き出しに含めることができます。identityMap
オブジェクト内のすべての ID も含まれます(Experience Platform は現在、HTTP API の宛先で ID マッピングをサポートしていません)。- マッピングされた属性のみが宛先の書き出しに含まれます。
例えば、HTTP 宛先に対するこのデータフローについて考えてみましょう。ここでは、3 つのオーディエンスがデータフローで選択され、4 つの属性が宛先にマッピングされます。
宛先へのプロファイルの書き出しは、3 つのマッピングされたセグメント のいずれかに適合またはいずれかを離脱するプロファイルによって決定されます。ただし、データの書き出しでは、segmentMembership
オブジェクト(以下の 書き出されたデータの節を参照)に、その特定のプロファイルがメンバーであり、書き出しをトリガーしたオーディエンスと同じ結合ポリシーを共有している場合、マッピングされていない他のオーディエンスが表示されることがあります。 プロファイルが デロリアンを保有する顧客 セグメントに適合すると同時に、「Watched "Back to the Future" 映画および SF ファン セグメントのメンバーでもある場合、他の 2 つのオーディエンスもデータ書き出しの segmentMembership
オブジェクトに表示されます。ただし、これらのオーディエンスが デロリアンを保有する顧客 セグメントと同じ結合ポリシーを共有すると、データフローでマッピングされません。
プロファイル属性の観点から、上記でマッピングした 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"
}
]
}
}
書き出されたデータのその他の例を以下に示します。これらは「セグメント名を含める」および「セグメントのタイムスタンプを含める」オプションに対して接続データフローで選択した UI 設定によって異なります。
segmentMembership
セクションにオーディエンス名が含まれていますcode language-json |
---|
|
segmentMembership
セクションにオーディエンスのタイムスタンプが含まれていますcode language-json |
---|
|
制限と再試行ポリシー limits-retry-policy
Experience Platform は 95% の確率で、HTTP 宛先の各データフローにおいて、送信に成功したメッセージのスループット待ち時間を 10 分未満、リクエスト数を 1 秒あたり 10,000 件未満で提供しようと試みます。
HTTP API 宛先へのリクエストが失敗した場合、Experience Platform は失敗したリクエストを保存し、リクエストをエンドポイントに送信するために 2 回再試行します。