Batch Decisioning API を使用したオファーの配信

Batch Decisioning API を使用すると、1 回の呼び出しの特定のセグメントで、すべてのプロファイルに対して、Offer Decisioning 機能を使用できます。セグメント内の各プロファイルに対するオファーコンテンツは、Adobe Experience Platform データセットに配置され、カスタムバッチワークフローで使用できます。

Batch Decisioning API を使用すると、決定範囲に関する Adobe Experience Platform セグメントのすべてのプロファイルにとって最適なオファーを、データセットに入力できます。例えば、ある組織が Batch Decisioning を実行して、メッセージ配信ベンダーにオファーを送信できるようにします。その後、これらのオファーは、同じセグメントのユーザーに対してバッチメッセージ配信用に送信されるコンテンツとして使用されます。

これを実現するため、組織は次の手順を実行します。

  • 次の 2 つのリクエストを含む Batch Decisioning API を実行します。

    1. バッチ POST リクエスト​で、オファーの選択をバッチ処理するワークロードを開始します。

    2. バッチ GET リクエスト​で、バッチのワークロードステータスを取得します。

  • データセットをメッセージ配信ベンダー API にエクスポートします。

はじめに

この API を使用する前に、次の前提条件の手順を実行してください。

決定の準備

次の手順に従って、1 つ以上の決定に対する準備を行います。

  • 決定結果をエクスポートするには、「ODE DecisionEvents」スキーマを使用してデータセットを作成します。

  • 評価してから更新する Platform セグメントを作成します。セグメントメンバーシップ評価の更新方法については、セグメント化ドキュメントを参照してください。

  • Adobe Journey Optimizer で、決定(決定 ID とプレースメント ID で構成される決定範囲を持つ)を作成します。詳しくは、決定作成に関するガイドの決定範囲の定義に関する節を参照してください。

API の要件

すべての Batch Decisioning リクエストには、Decision Management API 開発者ガイドで言及されているものに加え、次のヘッダーが必要になります。

  • Content-Typeapplication/json
  • x-request-id:リクエストを識別する一意の文字列。
  • x-sandbox-name:サンドボックス名。
  • x-sandbox-id:サンドボックス ID。

バッチ処理の開始

ワークロードを開始して決定をバッチ処理するには、/workloads/decisions エンドポイントに対して POST リクエストを実行します。

API 形式

POST {ENDPOINT_PATH}/{CONTAINER_ID}/workloads/decisions
パラメーター 説明
{ENDPOINT_PATH} リポジトリ API のエンドポイントパス。 https://platform.adobe.io/data/core/ode
{CONTAINER_ID} 決定が配置されているコンテナ。 e0bd8463-0913-4ca1-bd84-6309134ca1f6

リクエスト

curl -X POST 'https://platform.adobe.io/data/core/ode/0948b1c5-fff8-3b76-ba17-909c6b93b5a2/workloads/decisions' \
-H 'x-request-id: f671a589-eb7b-432f-b6b9-23d5b796b4dc' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-sandbox-id: {SANDBOX_ID}' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-d '{
  "xdm:segmentIds": [
    "609028e4-e66c-4776-b0d9-c782887e2273"
  ],
  "xdm:dataSetId": "6196b4a1a63bd118dafe093c",
  "xdm:propositionRequests": [
        {
            "xdm:activityId": "xcore:offer-activity:1410cdcda196707b",
            "xdm:placementId": "xcore:offer-placement:1410c4117306488a",
            "xdm:itemCount": 1
        }
  ],
  "xdm:includeContent": false
}'
プロパティ 説明
xdm:segmentIds 値は、セグメントの一意の ID を含む配列です。値を 1 つだけ含めることができます。 609028e4-e66c-4776-b0d9-c782887e2273
xdm:dataSetId 決定イベントを書き込むことができる出力データセット。 6196b4a1a63bd118dafe093c
xdm:propositionRequests placementId および activityId を含むラッパー
xdm:activityId 決定の一意の ID。 xcore:offer-activity:1410cdcda196707b
xdm:placementId 一意のプレースメント ID。 xcore:offer-placement:1410c4117306488a
xdm:itemCount 決定範囲に対してリクエストされたオプションなどの項目数を示すオプションのフィールドです。デフォルトでは、API は範囲ごとに 1 つのオプションを返しますが、このフィールドを指定することで、より多くのオプションを明示的に求めることができます。1 つの範囲につき、最低 1 個、最大 30 個のオプションをリクエストできます。 1
xdm:includeContent これはオプションのフィールドで、デフォルトでは false です。true の場合、オファーのコンテンツは、データセットの決定イベントに含まれます。 false

詳しくは、意志決定管理ドキュメントで、主な概念とプロパティの概要を参照してください。

応答

{
    "@id": "47efef25-4bcf-404f-96e2-67c4f784a1f5",
    "xdm:imsOrgId": "9GTO98D5F@AdobeOrg",
    "xdm:containerId": "0948b1c5-fff8-3b76-ba17-909c6b93b5a2",
    "ode:createDate": 1648078924834,
    "ode:status": "QUEUED"
}
プロパティ 説明
@id 単一のワークロードを識別する Offer decisioning によって生成される UUID。 5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8
xdm:imsOrgId 組織 ID。 9GTO98D5F@AdobeOrg
xdm:containerId コンテナ ID。 0948b1c5-fff8-3b76-ba17-909c6b93b5a2
ode:createDate 決定ワークロードリクエストが作成された時間。 1648078924834
ode:status ワークロードのステータス。 ode:status: "QUEUED"

バッチ決定に関する情報の取得

特定の決定に関する情報を取得するには、/workloads/decisions エンドポイントに対して GET リクエストを実行し、決定に対応するワークロード ID 値を指定します。

API 形式

GET  {ENDPOINT_PATH}/{CONTAINER_ID}/workloads/decisions/{WORKLOAD_ID}
パラメーター 説明
{ENDPOINT_PATH} リポジトリ API のエンドポイントパス。 https://platform.adobe.io/data/core/ode
{CONTAINER_ID} 決定が配置されているコンテナ。 e0bd8463-0913-4ca1-bd84-6309134ca1f6
{WORKLOAD_ID} 単一のワークロードを識別する Offer decisioning によって生成される UUID。 47efef25-4bcf-404f-96e2-67c4f784a1f5

リクエスト

curl -X GET 'https://platform.adobe.io/data/core/ode/0948b1c5-fff8-3b76-ba17-909c6b93b5a2/workloads/decisions/f395ab1f-dfaf-48d4-84c9-199ad6354591' \
-H 'x-request-id: 7832a42a-d4e5-413b-98e8-e49bef056436' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H'x-sandbox-id: {SANDBOX_ID}' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

応答

{
    "@id": "f395ab1f-dfaf-48d4-84c9-199ad6354591",
    "xdm:imsOrgId": "{IMS_ORG}",
    "xdm:containerId": "0948b1c5-fff8-3b76-ba17-909c6b93b5a2",
    "ode:createDate": 1648076994405,
    "ode:status": "COMPLETED"
}
プロパティ 説明
@id 単一のワークロードを識別する Offer decisioning によって生成される UUID。 5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8
xdm:imsOrgId 組織 ID 9GTO98D5F@AdobeOrg
xdm:containerId コンテナ ID 0948b1c5-fff8-3b76-ba17-909c6b93b5a2
ode:createDate 決定ワークロードリクエストが作成された時間。 1648076994405
ode:status ワークロードのステータスは「待機中」で始まり、「処理中」、「取り込み中」、「完了」または「エラー」に変わります。 ode:status: "COMPLETED"
ode:statusDetail ステータスが「処理中」または「取り込み中」の場合は、sparkJobId や batchID などの詳細が表示されます。ステータスが「エラー」の場合は、エラーの詳細が表示されます。

サービスレベル

各バッチ判定の終了時間は、ワークロードが作成された時点から出力データセットで判定結果を使用できる時点までの期間です。 エンドツーエンドのバッチ決定時間に影響する主な要因は、POST リクエストペイロードのセグメントサイズです。実施要件を満たすオファーでグローバル頻度キャップが有効になっている場合、バッチ判定の完了にはさらに時間がかかります。 次に、対象となるオファーに対して頻度キャップを適用する場合と適用しない場合の両方で、それぞれのセグメントサイズのエンドツーエンドの処理時間の近似を示します。

実施要件を満たすオファーに対して頻度キャップを有効にした場合:

セグメントサイズ エンドツーエンドの処理時間
1 万件以下のプロファイル 7 分
100 万件以下のプロファイル 30 分
1,500 万件以下のプロファイル 50 分

実施要件を満たすオファーの頻度キャップがない場合:

セグメントサイズ エンドツーエンドの処理時間
1 万件以下のプロファイル 6 分
100 万件以下のプロファイル 8 分
1,500 万件以下のプロファイル 16 分

制限事項

Batch Decisioning API を使用する場合、 次の制限に注意してください。

  • データセットごとの実行中のバッチジョブの数:データセットごとに一度に最大 5 つのバッチジョブを実行できます。同じ出力データセットを持つその他のバッチリクエストがキューに追加されます。前のジョブの実行が完了したら、キュー内のジョブがピックアップされ処理されます。
  • フリークエンシーキャップ:1 日に 1 回、プロファイルスナップショットからバッチが実行されます。Batch Decisioning API は頻度を制限し、常に最新のスナップショットからプロファイルを読み込みます。

次の手順

この API ガイドでは、Batch Decisioning API を使用してワークロードのステータスを確認し、オファーを配信しました。詳しくは、意思決定管理の概要を参照してください。

このページ