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