Segmentation Service APIを使用してセグメントを作成する

このドキュメントでは、Adobe Experience Platform Segmentation Service APIを使用してセグメント定義を開発、テスト、プレビュー、および保存するためのチュートリアルを提供します。

ユーザーインターフェイスを使用したセグメントの作成方法について詳しくは、セグメントビルダーガイドを参照してください。

はじめに

このチュートリアルでは、オーディエンスセグメントの作成に関わる様々なAdobe Experience Platformサービスについて、十分に理解している必要があります。 このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。

以下の節では、Platform APIを正しく呼び出すために知っておく必要がある追加情報について説明します。

API 呼び出し例の読み取り

このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。この中には、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。サンプル API 呼び出しのドキュメントで使用されている規則については、Experience Platform トラブルシューテングガイドのサンプル API 呼び出しの読み方に関する節を参照してください。

必須ヘッダーの値の収集

Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Experience Platform内のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Platform APIへのすべてのリクエストには、操作が行われるサンドボックスの名前を指定するヘッダーが必要です。

  • x-sandbox-name: {SANDBOX_NAME}
メモ

Platformのサンドボックスについて詳しくは、サンドボックスの概要ドキュメントを参照してください。

ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。

  • Content-Type: application/json

セグメント定義の作成

セグメント化の最初の手順は、セグメントを定義することです。セグメントは、セグメント定義と呼ばれる構成体で表されます。セグメント定義は、Profile Query Language (PQL)に書き込まれたクエリをカプセル化するオブジェクトです。 このオブジェクトは PQL 述語とも呼ばれます。PQL述語は、Real-time Customer Profileに指定するレコードや時系列データに関連する条件に基づいて、セグメントの規則を定義します。 PQL クエリの記述について詳しくは、PQL ガイドを参照してください。

Segmentation APIの/segment/definitionsエンドポイントにPOSTリクエストを行うことで、新しいセグメント定義を作成できます。 次の例では、セグメントを正しく定義するために必要な情報など、定義リクエストの形式について説明します。

セグメントの定義方法に関する詳細な説明は、『セグメント定義開発者ガイド』を参照してください。

オーディエンスの推定とプレビュー

セグメント定義を作成する際、Real-time Customer Profile内の予測ツールとプレビューツールを使用して、概要レベルの情報を表示し、期待されるオーディエンスを確実に特定できます。 推定を通じて、予想されるオーディエンスサイズや信頼区間など、セグメント定義の統計情報が得られます。プレビューは、セグメント定義に適格なプロファイルのページ分割リストを表示するので、結果を予想と比較できます。

オーディエンスの推定とプレビューにより、望ましい結果が得られるまで PQL 述語をテストし最適化することができます。最終的な PQL 述語は更新したセグメント定義で使用できます。

セグメントをプレビューまたは推定するために必要な手順は次の 2 つです。

  1. プレビュージョブの作成
  2. 推定またはプレビューの表示(プレビュージョブの ID を使用)

推定の生成方法

データサンプルを使用してセグメントを評価し、適格なプロファイルの数を推定します。毎朝(UTC の午前 7~9 時)新しいデータがメモリに読み込まれ、その日のサンプルデータを使用して、すべてのセグメント化クエリが推定されます。その結果、新しく追加されたフィールドや収集された追加データは、翌日の推定に反映されます。

サンプルサイズは、プロファイルストア内のエンティティの総数によって異なります。これらのサンプルサイズを次の表に示します。

プロファイルストア内のエンティティ数 サンプルサイズ
100 万未満 フルデータセット
100 万~2000 万 100 万
2000 万以上 全体の 5%

推定は通常、10~15 秒間実行されます。最初は大まかな推定ですが、読み取るレコードが増えるにつれて精度が高くなります。

プレビュージョブの作成

新しいプレビュージョブを作成するには、/preview エンドポイントに POST リクエストを送信します。

プレビュージョブの作成に関する詳細な手順は、『プレビューおよび予測エンドポイントガイド』を参照してください。

推定またはプレビューの表示

クエリが異なると完了するまでの時間が異なる可能性があるので、推定プロセスとプレビュープロセスは非同期で実行されます。クエリが開始されたら、API 呼び出しを使用して、推定またはプレビューの現在の状態を進行に応じて取得できます(GET リクエストを使用)。

Segmentation Service APIを使用して、プレビュージョブの現在の状態をIDで参照できます。 状態が「RESULT_READY」の場合は、結果を表示できます。プレビュージョブの現在の状態を調べるには、プレビューおよび推定エンドポイントガイドのプレビュージョブセクションの取得に関する節を読んでください。 見積もりジョブの現在の状態を調べるには、プレビューおよび見積もりエンドポイントガイドの見積もりジョブの取得に関する節を読んでください。

次の手順

セグメント定義の開発、テスト、保存が完了したら、Segmentation Service APIを使用してオーディエンスを構築するセグメントジョブを作成できます。 その詳しい手順については、セグメント結果の評価とアクセスに関するチュートリアルを参照してください。

このページ