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

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

はじめに

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

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

必須ヘッダー

また、このチュートリアルでは、 API の呼び出しを正常におこなうために、認証に関するチュートリアルを完了している必要があります。Platform次に示すように、すべての 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

セグメントの評価

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

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

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

スケジュールされた評価

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

メモ

XDM Individual Profileに対して、最大5個のマージポリシーを持つサンドボックスに対して、スケジュールされた評価を有効にできます。 1つのサンドボックス環境内にXDM Individual Profileのマージポリシーが5つを超える場合、スケジュールされた評価を使用できません。

スケジュールの作成

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

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

スケジュールの有効化

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

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

スケジュール時間の更新

/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": "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 つの方法では、オーディエンス全体をデータセットにエクスポートします。

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

プロファイルの検索

アクセスしたい特定のプロファイルを知っている場合は、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 Schema APIを使用して、データセットを参照するデータセットの作成方法につい Catalog て説明します。
  • **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
    }
}'
プロパティ 説明
name データセットのわかりやすい名前。
schemaRef.id データセットが関連付けられる和集合表示(スキーマ)の ID。
fileDescription.persisted ブール値。true に設定した場合、データセットが和集合表示に保持されます。

応答

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

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

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

和集合持続性データセットを取得したら、Real-time Customer Profile APIの/export/jobsエンドポイントにPOSTリクエストを送信し、エクスポートするセグメントのデータセットIDとセグメント情報を提供することで、オーディエンスをデータセットに永続化するエクスポートジョブを作成できます。

このエンドポイントの使用に関する詳細は、export jobs endpoint guideを参照してください

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

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

このエンドポイントの使用に関する詳細は、export jobs endpoint guideを参照してください

次の手順

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

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

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

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

このページ

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now