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

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

はじめに

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

必須ヘッダー

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

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

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

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

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

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

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

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