[Ultimate]{class="badge positive"}

HTTP API 接続

概要 overview

IMPORTANT
この宛先を使用できるのは Adobe Real-time Customer Data Platform Ultimate の顧客のみです。

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

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

ユースケース use-cases

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

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

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

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

オーディエンスオリジン
サポートあり
説明
Segmentation Service
Experience Platform セグメント化サービスを通じて生成されたオーディエンス。
カスタムアップロード
CSV ファイルから Experience Platform に読み込まれたオーディエンス。

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

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

項目
タイプ
メモ
書き出しタイプ
プロファイルベース
セグメントのすべてのメンバーを、宛先のアクティベーションワークフローのマッピング画面で選択したように、必要なスキーマフィールド(例:メールアドレス、電話番号、姓)とともに書き出します。
書き出し頻度
ストリーミング
ストリーミングの宛先は常に、API ベースの接続です。オーディエンス評価に基づいて Experience Platform 内でプロファイルが更新されるとすぐに、コネクタは更新を宛先プラットフォームに送信します。ストリーミングの宛先の詳細についてはこちらを参照してください。

前提条件 prerequisites

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

  • REST API をサポートする HTTP エンドポイントが必要です。
  • 使用する HTTP エンドポイントが、Experience Platform プロファイルスキーマをサポートする必要があります。HTTP API 宛先では、サードパーティのペイロードスキーマへの変換はサポートされていません。Experience Platform の出力スキーマの例については、書き出されたデータの節を参照してください。
  • HTTP エンドポイントはヘッダーをサポートする必要があります。
TIP
また、Adobe Experience Platform Destination SDK を使用して統合環境を設定し、HTTP エンドポイントに Experience Platform プロファイルデータを送信することもできます。

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)をチェックしてサードパーティの検証を追加する場合は、以下の証明書をダウンロードできます。

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>'
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

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

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

認証情報 authentication-information

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

ベアラートークン ​認証タイプを選択して、HTTP エンドポイントに接続する場合は、以下のフィールドを入力し、「宛先に接続」を選択します。

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

  • ベアラートークン:ベアラートークンを挿入して、HTTP ロケーションに対する認証を行います。

認証なし no-authentication

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

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

この認証を開いた状態で選択する場合は、「宛先に接続」を選択するだけで、エンドポイントへの接続が確立されます。

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

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

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

  • アクセストークン 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 エンドポイントに接続する場合は、以下のフィールドを入力し、「宛先に接続」を選択します。

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

  • アクセストークン 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 のフィールドの横のアスタリスクは、そのフィールドが必須であることを示します。

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

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

アラートの有効化 enable-alerts

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

宛先接続の詳細の入力を終えたら「次へ」を選択します。

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

IMPORTANT
  • データをアクティブ化するには、宛先の表示宛先のアクティブ化プロファイルの表示 および セグメントの表示 アクセス制御権限が必要です。 アクセス制御の概要を参照するか、製品管理者に問い合わせて必要な権限を取得してください。
  • 同意ポリシーの評価は現在、HTTP API 宛先への書き出しではサポートされていません。 詳細情報

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

宛先属性 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 つの属性が宛先にマッピングされます。

HTTP API 宛先のデータフローの例

宛先へのプロファイルの書き出しは、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": {
        "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"
          }
        }
      }
以下のデータの書き出しの例では、segmentMembership セクションにオーディエンスのタイムスタンプが含まれています
code language-json
"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 宛先の各データフローにおいて、送信に成功したメッセージのスループット待ち時間を 10 分未満、リクエスト数を 1 秒あたり 10,000 件未満で提供しようと試みます。

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

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6