セグメント定義結果の評価とアクセス

このドキュメントでは、セグメント定義を評価し、Segmentation API を使用してこれらの結果にアクセスするためのチュートリアルを提供します。

はじめに

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

必須ヘッダー

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

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

すべての POST、PUT、および PATCH リクエストには、次の追加ヘッダーが必要です。

セグメント定義の評価 evaluate-a-segment

セグメント定義を開発、テスト、保存したら、スケジュールに沿った評価またはオンデマンド評価を行って、セグメント定義を評価できます。

スケジュールされた評価 （「スケジュールされたセグメント化」とも呼ばれる）では、特定の時間にエクスポートジョブを実行する定期的なスケジュールを作成できます。オンデマンド評価では、オーディエンスを即座に構築するセグメントジョブを作成できます。それぞれの評価の手順を以下に示します。

Segmentation API を使用したセグメント定義の作成チュートリアルをまだ完了していない場合、または セグメントビルダーを使用してセグメント定義を作成した場合は、このチュートリアルに進む前に行ってください。

スケジュールされた評価 scheduled-evaluation

スケジュールされた評価を通じて、組織は繰り返しスケジュールを作成して、書き出しジョブを自動的に実行できます。

スケジュールの作成

/config/schedules エンドポイントに対して POST リクエストを実行することにより、スケジュールを作成し、スケジュールをトリガーする必要がある特定の時間を指定することができます。

このエンドポイントの使用について詳しくは、 スケジュールエンドポイントガイドを参照してください

スケジュールの有効化

デフォルトでは、作成（POST）リクエスト本文で state プロパティが active に設定されていない限り、スケジュールは作成時に非アクティブになります。/config/schedules エンドポイントに対して PATCH リクエストを実行し、パスにスケジュールの ID を含めることで、スケジュールを有効にする（state を active に設定する）ことができます。

このエンドポイントの使用について詳しくは、 スケジュールエンドポイントガイドを参照してください

スケジュール時間の更新

/config/schedules エンドポイントに対して PATCH リクエストを実行し、スケジュールの ID をパスに含めることで、スケジュールのタイミングを更新できます。

このエンドポイントの使用について詳しくは、 スケジュールエンドポイントガイドを参照してください

オンデマンド評価

オンデマンド評価を使用すると、セグメントジョブを作成して、必要なときにいつでもオーディエンスを生成できます。 スケジュールされた評価とは異なり、セグメントの生成はリクエストされた場合にのみ発生し、定期的に実行されません。

セグメントジョブの作成

セグメントジョブは、オーディエンスセグメントをオンデマンドで作成する非同期プロセスです。 セグメント定義と、プロファイルフラグメント間で重複する属性の結合方法を制御する結合ポリシー Real-Time Customer Profile 参照します。 セグメントジョブが正常に完了すると、処理中に発生した可能性のあるエラーやオーディエンスの最終的なサイズなど、セグメント定義に関する様々な情報を収集できます。 セグメントジョブは、そのセグメント定義が現在該当するオーディエンスを更新するたびに実行する必要があります。

Real-Time Customer Profile API の /segment/jobs エンドポイントに対してセグメントリクエストを実行することで、新しいPOSTジョブを作成できます。

このエンドポイントの使用について詳しくは、 セグメントジョブエンドポイントガイドを参照してください。

セグメントジョブステータスの検索

特定のセグメントジョブの 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"
      }
    }
  }
}

セグメントジョブの結果へのアクセス

セグメントジョブの結果には、2 つの方法のいずれかでアクセスできます。1 つの方法では、個々のプロファイルにアクセスし、もう 1 つの方法では、オーディエンス全体をデータセットにエクスポートします。

以下の節では、これらのオプションの概要を詳しく説明します。

プロファイルの検索

アクセスする特定のプロファイルがわかっている場合は、Real-Time Customer Profile API を使用してアクセスできます。 個々のプロファイルにアクセスする完全な手順については、チュートリアル プロファイル API を使用したリアルタイム顧客プロファイルデータへのアクセスを参照してください。

セグメントのエクスポート export

セグメントジョブが正常に完了したら（status 属性の値は「SUCCEEDED」）、オーディエンスをデータセットにエクスポートして、オーディエンスにアクセスし、処理をおこなうことができます。

オーディエンスをエクスポートするには、次の手順を実行する必要があります。

ターゲットデータセットの作成 create-dataset

オーディエンスをエクスポートする場合は、まずターゲットデータセットを作成する必要があります。データセットを正しく設定して、エクスポートが正常に行われるようにすることが重要です。

重要な考慮事項の 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"
    }
}'

応答

応答に成功した場合、新しく作成されたデータセットの読み取り専用のシステム生成された一意の ID を含む配列が返されます。オーディエンスメンバーを正常にエクスポートするには、適切に設定されたデータセット ID が必要です。

[
  "@/datasets/5b020a27e7040801dedba61b"
]

オーディエンスメンバーのプロファイルの生成 generate-profiles

和集合を保持するデータセットが用意できたら、Real-Time Customer Profile API の /export/jobs エンドポイントに対してPOSTリクエストを行い、書き出すセグメント定義のデータセット ID とセグメント定義情報を指定することで、オーディエンスメンバーをデータセットに保持する書き出しジョブを作成できます。

このエンドポイントの使用について詳しくは、 書き出しジョブエンドポイントガイドを参照してください。

エクスポートの進行状況の監視

エクスポートジョブを処理するときに、/export/jobs エンドポイントに対して GET リクエストを実行し、エクスポートジョブの id をパスを含めることで、エクスポートジョブのステータスを監視することができます。status フィールドによって値「SUCCEEDED」が返されると、エクスポートジョブが完了します。

このエンドポイントの使用について詳しくは、 書き出しジョブエンドポイントガイドを参照してください。

次の手順

書き出しが正常に完了すると、Experience Platform の Data Lake 内でデータを使用できるようになります。 その後、Data Access API を使用して、書き出しに関連付けられた batchId を使用してデータにアクセスできます。 セグメント定義のサイズによっては、データがチャンクにまとめられ、バッチが複数のファイルで構成される場合があります。

Data Access API を使用してバッチファイルにアクセスし、ダウンロードする手順については、 データアクセスのチュートリアルに従ってください。

また、Adobe Experience Platform Query Service を使用して、正常に書き出されたセグメント定義データにアクセスすることもできます。 UI または RESTful API を使用す Query Service と、Data Lake 内のデータに対するクエリを記述、検証および実行できます。

オーディエンスデータのクエリ方法について詳しくは、Query Service のドキュメントを参照してください。