このドキュメントでは、 Segmentation API.
このチュートリアルでは、 Adobe Experience Platform オーディエンスセグメントの作成に関係するサービス。 このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。
また、このチュートリアルでは、 API の呼び出しを正常におこなうために、認証に関するチュートリアルを完了している必要があります。Platform次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。へのリクエスト Platform API には、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
{SANDBOX_NAME}
Platform のサンドボックスについて詳しくは、サンドボックスの概要に関するドキュメントを参照してください。
すべての POST、PUT、および PATCH リクエストには、次の追加ヘッダーが必要です。
セグメント定義を開発、テスト、保存したら、スケジュールされた評価またはオンデマンド評価を通じてセグメントを評価できます。
スケジュールされた評価 (「スケジュールされたセグメント化」とも呼ばれる)では、特定の時間にエクスポートジョブを実行する定期的なスケジュールを作成できます。オンデマンド評価では、オーディエンスを即座に構築するセグメントジョブを作成できます。それぞれの評価の手順を以下に示します。
まだ セグメント化 API を使用してセグメントを作成する チュートリアルを使用するか、 セグメントビルダーを使用する場合は、このチュートリアルに進む前におこないます。
組織は、スケジュールされた評価を通じて、書き出しジョブを自動的に実行する定期的なスケジュールを作成できます。
XDM Individual Profile の最大 5 つの結合ポリシーを備えたサンドボックスに対して、スケジュールされた評価を有効にできます。組織で、1 つのサンドボックス環境内に XDM Individual Profile の結合ポリシーが 6 つ以上ある場合は、スケジュールされた評価を使用できません。
/config/schedules
エンドポイントに対して POST リクエストを実行することにより、スケジュールを作成し、スケジュールをトリガーする必要がある特定の時間を指定することができます。
このエンドポイントの使用に関する詳細については、 スケジュールエンドポイントガイド
デフォルトでは、作成(POST)リクエスト本文で state
プロパティが active
に設定されていない限り、スケジュールは作成時に非アクティブになります。/config/schedules
エンドポイントに対して PATCH リクエストを実行し、パスにスケジュールの ID を含めることで、スケジュールを有効にする(state
を active
に設定する)ことができます。
このエンドポイントの使用に関する詳細については、 スケジュールエンドポイントガイド
/config/schedules
エンドポイントに対して PATCH リクエストを実行し、スケジュールの ID をパスに含めることで、スケジュールのタイミングを更新できます。
このエンドポイントの使用に関する詳細については、 スケジュールエンドポイントガイド
オンデマンド評価を使用すると、必要に応じてオーディエンスセグメントを生成するためのセグメントジョブを作成できます。スケジュールされた評価とは異なり、セグメントの生成はリクエストされた場合にのみ発生し、定期的に実行されません。
セグメントジョブは、オーディエンスセグメントをオンデマンドで作成する非同期プロセスです。 セグメント定義と、その方法を制御する結合ポリシーを参照します Real-Time Customer Profile は、複数のプロファイルフラグメントで重複している属性を結合します。 セグメントジョブが正常に完了したら、処理中に発生したエラーやオーディエンスの最大サイズなど、セグメントに関する様々な情報を収集できます。セグメント定義に現在適合しているオーディエンスを更新するたびに、セグメントジョブを実行する必要があります。
新しいセグメントジョブを作成するには、 /segment/jobs
エンドポイント Real-Time Customer Profile API
このエンドポイントの使用に関する詳細については、 セグメントジョブエンドポイントガイド
特定のセグメントジョブの id
を使用して、ルックアップリクエスト(GET)を実行すると、ジョブの現在のステータスを表示できます。
このエンドポイントの使用に関する詳細については、 セグメントジョブエンドポイントガイド
セグメントジョブが正常に実行されると、セグメント内に含まれる各プロファイルの segmentMembership
マップが更新されます。segmentMembership
また、には、 Platformを使用して、 Adobe Audience Manager.
次の例は、個々のプロファイルレコードの segmentMembership
属性がどのように記述されるかを示しています。
{
"segmentMembership": {
"UPS": {
"04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
"timestamp": "2018-04-26T15:52:25+00:00",
"status": "realized"
},
"53cba6b2-a23b-454a-8069-fc41308f1c0f": {
"lastQualificationTime": "2018-04-26T15:52:25+00:00",
"status": "realized"
}
},
"Email": {
"abcd@adobe.com": {
"lastQualificationTime": "2017-09-26T15:52:25+00:00",
"status": "exited"
}
}
}
}
プロパティ | 説明 |
---|---|
lastQualificationTime |
セグメントメンバーシップのアサーションが行われて、プロファイルがセグメントに出入りしたときのタイムスタンプ。 |
status |
現在のリクエストの一部としてのセグメント参加のステータス。次の既知の値のいずれかと等しい必要があります。
|
次に属する任意のセグメントメンバーシップ exited
30 日を超えるステータス ( lastQualificationTime
、は削除される可能性があります。
セグメントジョブの結果には、2 つの方法のいずれかでアクセスできます。1 つの方法では、個々のプロファイルにアクセスし、もう 1 つの方法では、オーディエンス全体をデータセットにエクスポートします。
以下の節では、これらのオプションの概要を詳しく説明します。
アクセスする特定のプロファイルがわかっている場合は、 Real-Time Customer Profile API 個々のプロファイルにアクセスするための完全な手順は、 プロファイル API を使用したリアルタイム顧客プロファイルデータへのアクセス チュートリアル
セグメントジョブが正常に完了したら(status
属性の値は「SUCCEEDED」)、オーディエンスをデータセットにエクスポートして、オーディエンスにアクセスし、処理をおこなうことができます。
オーディエンスをエクスポートするには、次の手順を実行する必要があります。
オーディエンスをエクスポートする場合は、まずターゲットデータセットを作成する必要があります。データセットを正しく設定して、エクスポートが正常に行われるようにすることが重要です。
重要な考慮事項の 1 つは、データセットのベースとなるスキーマ(以下の API サンプルリクエストの schemaRef.id
)です。セグメントをエクスポートするには、データセットが XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union
) をクリックします。 和集合スキーマは、システム生成された読み取り専用のスキーマであり、同じクラス(この場合は XDM 個別プロファイルクラス)を共有するスキーマのフィールドを集計します。和集合表示スキーマについて詳しくは、 スキーマレジストリ開発者ガイドの「リアルタイム顧客プロファイル」の節.
必要なデータセットを作成する方法は 2 つあります。
互換性のあるデータセットが既に存在し、その ID がわかっている場合は、オーディエンスプロファイルを生成する手順に直接進むことができます。
API 形式
POST /dataSets
リクエスト
次のリクエストは、新しいデータセットを作成し、ペイロードに設定パラメーターを提供します。
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Segment Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
プロパティ | 説明 |
---|---|
name |
データセットのわかりやすい名前。 |
schemaRef.id |
データセットが関連付けられる和集合表示(スキーマ)の ID。 |
応答
応答に成功した場合、新しく作成されたデータセットの読み取り専用のシステム生成された一意の ID を含む配列が返されます。オーディエンスメンバーを正常にエクスポートするには、適切に設定されたデータセット ID が必要です。
[
"@/datasets/5b020a27e7040801dedba61b"
]
和集合永続化データセットを取得したら、に対してPOSTリクエストを実行することで、オーディエンスメンバーをデータセットに保持する書き出しジョブを作成できます /export/jobs
エンドポイント Real-Time Customer Profile API を使用し、書き出すセグメントのデータセット ID とセグメント情報を指定します。
このエンドポイントの使用に関する詳細については、 書き出しジョブエンドポイントガイド
エクスポートジョブを処理するときに、/export/jobs
エンドポイントに対して GET リクエストを実行し、エクスポートジョブの id
をパスを含めることで、エクスポートジョブのステータスを監視することができます。status
フィールドによって値「SUCCEEDED」が返されると、エクスポートジョブが完了します。
このエンドポイントの使用に関する詳細については、 書き出しジョブエンドポイントガイド
エクスポートが正常に完了すると、データは Data Lake in Experience Platform. その後、 Data Access API を使用してデータにアクセスするには batchId
をエクスポートに関連付けました。 セグメントのサイズに応じて、データがチャンクに格納され、バッチが複数のファイルで構成される場合があります。
の使用方法に関する詳細な手順については、 Data Access バッチファイルにアクセスしてダウンロードする API では、 データアクセスのチュートリアル.
また、 Adobe Experience Platform Query Service. UI または RESTful API の使用 Query Service では、 Data Lake.
オーディエンスデータに対してクエリを実行する方法の詳細については、 Query Service.