Segmentation Service API を使用したセグメント定義の作成
このドキュメントでは、を使用したセグメント定義の開発、テスト、プレビューおよび保存に関するチュートリアルを提供します Adobe Experience Platform Segmentation Service API.
ユーザーインターフェイスを使用してセグメント定義を作成する方法について詳しくは、 セグメントビルダーガイド.
はじめに
このチュートリアルでは、様々な Adobe Experience Platform セグメント定義の作成に関連するサービス。 このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。
- Real-Time Customer Profile：複数のソースから集計したデータに基づいて、統合されたリアルタイム顧客プロファイルを提供します。
- Adobe Experience Platform Segmentation Service：セグメント定義またはリアルタイム顧客プロファイルデータのその他の外部ソースを使用して、オーディエンスを作成できます。
- Experience Data Model (XDM)：Platform が、カスタマーエクスペリエンスデータを整理する際に使用する、標準化されたフレームワーク。セグメント化を最大限に活用するには、データモデリングのベストプラクティスに従って、データがプロファイルとイベントとして取り込まれていることを確認してください。
以下の節では、を正しく呼び出すために知っておく必要がある追加情報を示します Platform API です。
API 呼び出し例の読み取り
このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーの値の収集
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization： Bearer
{ACCESS_TOKEN} - x-api-key：
{API_KEY} - x-gw-ims-org-id：
{ORG_ID}
Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
- x-sandbox-name：
{SANDBOX_NAME}
ペイロード（POST、PUT、PATCH）を含むすべてのリクエストには、次のような追加ヘッダーが必要です。
- Content-Type: application/json
セグメント定義の作成
セグメント化の最初の手順は、セグメント定義を定義することです。 セグメント定義は、で記述されたクエリをカプセル化するオブジェクトです。 Profile Query Language （PQL）。 このオブジェクトは、PQL述語とも呼ばれます。 PQLの述語は、提供するレコードまたは時系列データに関連する条件に基づいて、セグメント定義のルールを定義します Real-Time Customer Profile. PQL クエリの記述について詳しくは、PQL ガイドを参照してください。
に対してPOSTリクエストを実行することで、新しいセグメント定義を作成できます。 /segment/definitions のエンドポイント Segmentation API です。 次の例では、セグメント定義を正常に定義するために必要な情報など、定義リクエストのフォーマット方法の概要を説明します。
セグメント定義の定義方法の詳細については、を参照してください。 セグメント定義開発者ガイド.
オーディエンスの推定とプレビュー estimate-and-preview-an-audience
セグメント定義を作成する際は、内で予測ツールとプレビューツールを使用できます Real-Time Customer Profile を使用して概要レベルの情報を表示し、期待されるオーディエンスを確実に分離できるようにします。 推定を通じて、予想されるオーディエンスサイズや信頼区間など、セグメント定義の統計情報が得られます。プレビューは、セグメント定義に適格なプロファイルのページ分割リストを表示するので、結果を予想と比較できます。
オーディエンスの推定とプレビューにより、望ましい結果が得られるまで PQL 述語をテストし最適化することができます。最終的な PQL 述語は更新したセグメント定義で使用できます。
セグメント定義をプレビューまたは推定するには、次の 2 つの必須ステップがあります。
- プレビュージョブの作成
- 推定またはプレビューの表示（プレビュージョブの ID を使用）
推定の生成方法
リアルタイム顧客プロファイルに対して有効にされたデータは Platform に取り込まれるので、プロファイルデータストア内に保存されます。 プロファイルストアへのレコードの取り込みが、合計プロファイル数を 5% 以上増加または減少させると、サンプリングジョブがトリガーされて数が更新されます。 プロファイル数が 5% を超えて変化しない場合、サンプリングジョブは毎週自動的に実行されます。
サンプルをトリガーする方法は、使用する取り込みのタイプによって異なります。
- ストリーミングデータワークフローの場合は、5% の増加または減少のしきい値に達したかどうかを判断するために、1 時間ごとにチェックが行われます。 このしきい値に達すると、サンプルジョブが自動的にトリガーされ、カウントが更新されます。
- バッチ取り込みの場合、プロファイルストアにバッチを正常に取り込んでから 15 分以内に、5% の増減しきい値に達した場合は、ジョブを実行してカウントを更新します。 プロファイル API を使用すると、最新の成功したサンプルジョブをプレビューできるほか、データセット別および ID 名前空間別のプロファイル配布をリストできます。
サンプルサイズは、プロファイルストア内のエンティティの合計数によって異なります。 これらのサンプルサイズを次の表に示します。
推定は通常、10～15 秒間実行されます。最初は大まかな推定ですが、読み取るレコードが増えるにつれて精度が高くなります。
プレビュージョブの作成
新しいプレビュージョブを作成するには、/preview エンドポイントに POST リクエストを送信します。
プレビュージョブの作成に関する詳細な手順については、を参照してください。 プレビューと予測エンドポイントガイド.
推定またはプレビューの表示
クエリが異なると完了するまでの時間が異なる可能性があるので、推定プロセスとプレビュープロセスは非同期で実行されます。クエリが開始されたら、API 呼び出しを使用して、推定またはプレビューの現在の状態を進行に応じて取得できます（GET リクエストを使用）。
使用， Segmentation Service API を使用すると、プレビュージョブの現在の状態を ID で検索できます。 状態が「RESULT_READY」の場合は、結果を表示できます。プレビュージョブの現在の状態を検索するには、の節を参照してください。 プレビュージョブセクションの取得 を参照してください。 推定ジョブの現在の状態を検索するには、の節を参照してください。 見積ジョブの取得 を参照してください。
次の手順
セグメント定義を開発、テスト、保存したら、次を使用して、オーディエンスを作成するセグメントジョブを作成できます Segmentation Service API です。 その詳しい手順については、セグメント結果の評価とアクセスに関するチュートリアルを参照してください。