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

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

はじめに

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

必須ヘッダー

このチュートリアルでは、 認証のチュートリアル を正常に呼び出すために Platform API です。 次に示すように、すべての 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 プロファイルフラグメント間で重複する属性を結合します。 セグメントジョブが正常に完了すると、処理中に発生した可能性のあるエラーやオーディエンスの最終的なサイズなど、セグメント定義に関する様々な情報を収集できます。 セグメントジョブは、そのセグメント定義が現在該当するオーディエンスを更新するたびに実行する必要があります。

に対してジョブリクエストを実行することで、新しいセグメントPOSTを作成できます。 /segment/jobs のエンドポイント 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": "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 です。 個々のプロファイルにアクセスするための完全な手順については、を参照してください。 Profile 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

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

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

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

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

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

次の手順

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

の使い方に関する詳しい手順 Data Access バッチファイルにアクセスしてダウンロードするには、次の API に従います データアクセスのチュートリアル.

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

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