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

This document provides a tutorial for evaluating segments and accessing segment results using the Segmentation API.

はじめに

This tutorial requires a working understanding of the various Adobe Experience Platform services involved in creating audience segments. このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。

  • Real-time Customer Profile:複数のソースからの集計データに基づいて、リアルタイムで統合された顧客プロファイルを提供します。
  • Adobe Experience Platform Segmentation Service:データからオーディエンスセグメントを作成でき Real-time Customer Profile ます。
  • Experience Data Model (XDM):プラットフォームが顧客体験データを編成する際に使用する標準化されたフレームワーク。
  • サンドボックス: Experience Platform は、1つの Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスを提供します。

必須ヘッダー

また、このチュートリアルでは、 API の呼び出しを正常におこなうために、認証に関するチュートリアルを完了している必要があります。PlatformCompleting the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

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

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE

For more information on sandboxes in Platform, see the sandbox overview documentation.

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

  • Content-Type: application/json

セグメントの評価

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

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

If you have not yet completed the create a segment using the Segmentation API tutorial or created a segment definition using Segment Builder, please do so before proceeding with this tutorial.

スケジュールされた評価

IMS 組織では、スケジュールされた評価を通じて、エクスポートジョブを自動的に実行する定期的なスケジュールを作成できます。

NOTE

Scheduled evaluation can be enabled for sandboxes with a maximum of five (5) merge policies for XDM Individual Profile. If your organization has more than five merge policies for XDM Individual Profile within a single sandbox environment, you will not be able to use scheduled evaluation.

スケジュールの作成

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

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

スケジュールの有効化

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

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

スケジュール時間の更新

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

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

オンデマンド評価

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

セグメントジョブの作成

セグメントジョブは、新しいオーディエンスセグメントを作成する非同期プロセスです。It references a segment definition, as well as any merge policies controlling how Real-time Customer Profile merges overlapping attributes across your profile fragments. セグメントジョブが正常に完了したら、処理中に発生したエラーやオーディエンスの最大サイズなど、セグメントに関する様々な情報を収集できます。

You can create a new segment job by making a POST request to the /segment/jobs endpoint in the 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": "existing"
      },
      "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 現在のリクエストの一部としてのセグメント参加のステータス。次の既知の値のいずれかと等しい必要があります。
  • existing:エンティティが引き続きセグメント内に存在します。
  • realized:エンティティがセグメントに入っています。
  • exited:エンティティがセグメントから退出しています。

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

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

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

プロファイルの検索

If you know the specific profile that you would like to access, you can do so using the 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 つあります。

  • APIの使用: このチュートリアルで説明する手順は、 XDM Individual Profile Union SchemaCatalog APIを使用して、データセットを参照するデータセットを作成する方法を示しています。
  • **UI の使用:**Adobe Experience Platform のユーザーインターフェイスを使用して、和集合スキーマを参照するデータセットを作成するには、UI のチュートリアルの手順を実行してから、このチュートリアルに戻り、オーディエンスプロファイルを生成する手順に進みます。

互換性のあるデータセットが既に存在し、その 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: {IMS_ORG}' \
  -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"
    },
    "fileDescription": {
        "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    }
}'
プロパティ 説明
name データセットのわかりやすい名前。
schemaRef.id データセットが関連付けられる和集合表示(スキーマ)の ID。
fileDescription.persisted ブール値。true に設定した場合、データセットが和集合表示に保持されます。

応答

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

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

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

Once you have a union-persisting dataset, you can create an export job to persist the audience members to the dataset by making a POST request to the /export/jobs endpoint in the Real-time Customer Profile API and providing the dataset ID and the segment information for the segments that you wish to export.

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

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

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

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

次の手順

Once the export has completed successfully, your data is available within the Data Lake in Experience Platform. You can then use the Data Access API to access the data using the batchId associated with the export. セグメントのサイズに応じて、データがチャンクに格納され、バッチが複数のファイルで構成される場合があります。

For step-by-step instructions on how to use the Data Access API to access and download batch files, follow the Data Access tutorial.

また、を使用して、正常にエクスポートされたセグメントデータにアクセスすることもでき Adobe Experience Platform Query Serviceます。 Using the UI or RESTful API, Query Service allows you to write, validate, and run queries on data within the Data Lake.

For more information on how to query audience data, please review the documentation on Query Service.

このページ