アドホックアクティベーション APIを使用して、バッチ宛先にオンデマンドでオーディエンスをアクティベートできます

概要 overview

アドホックアクティベーション APIを使用すると、マーケターは、即座のアクティベーションが必要な状況に応じて、オーディエンスをプログラムによって宛先に迅速かつ効率的にアクティベートできます。

アドホックアクティベーション APIを使用して、フルファイルを目的のファイル受信システムに書き出します。 アドホックオーディエンスのアクティベーションは、​ バッチファイルベースの宛先でのみサポートされています。

次の図は、24時間ごとにExperience Platformで行われるセグメンテーションジョブを含む、アドホックアクティベーション APIを介してオーディエンスをアクティベートするエンドツーエンドのワークフローを示しています。

ユースケース use-cases

フラッシュセールまたはプロモーション flash-sales

オンラインのretailerは、期間限定のフラッシュセールを準備しており、短期間でお客様に通知したいと考えています。 Experience Platformのアドホックアクティベーション APIを使用することで、マーケティング部門はオーディエンスをオンデマンドで書き出し、顧客基盤にすばやくプロモーションメールを送信できます。

最新の出来事や速報 current-events

ホテルは翌日の悪天候を予想しており、チームは到着するゲストに迅速に通知したいので、それに応じて計画を立てることができます。 マーケティング部門は、Experience Platformのアドホックアクティベーション APIを使用して、オーディエンスをオンデマンドで書き出し、ゲストに通知できます。

統合テスト integration-testing

IT担当者は、Experience Platformのアドホックアクティベーション APIを使用してオーディエンスをオンデマンドで書き出すことができるため、Adobe Experience Platformとのカスタム統合をテストして、すべてが正しく動作していることを確認できます。

ガードレール guardrails

アドホックアクティベーション APIを使用する場合は、次のガードレールに注意してください。

セグメント化の考慮事項 segmentation-considerations

Adobe Experience Platformは、スケジュールされたセグメント化ジョブを24時間ごとに1回実行します。 アドホックアクティベーション APIは、最新のセグメント化結果に基づいて実行されます。

ステップ 1：前提条件 prerequisites

Adobe Experience Platform APIを呼び出す前に、次の前提条件を満たしていることを確認してください。

手順2：資格情報の収集 credentials

Experience Platform APIを呼び出すには、まず認証チュートリアル ​を完了する必要があります。 認証に関するチュートリアルを完了すると、すべての Experience Platform API 呼び出しで使用する、以下のような各必須ヘッダーの値が提供されます。

Experience Platform のリソースは、特定の仮想サンドボックスに分離することができます。Experience Platform APIへのリクエストでは、操作を実行するサンドボックスの名前とIDを指定できます。 次に、オプションのパラメーターを示します。

ペイロード（POST、PUT、PATCH）を含むすべてのリクエストには、メディアのタイプを指定する以下のような追加ヘッダーが必要です。

手順3:Experience Platform UIでのアクティベーションフローの作成 activation-flow

アドホックアクティベーション APIを使用してオーディエンスをアクティベートするには、まず、選択した宛先に対してExperience Platform UIでアクティベーションフローを設定する必要があります。

これには、アクティベーションワークフローに入り、オーディエンスを選択し、スケジュールを設定して、アクティベートすることなどが含まれます。 UIまたはAPIを使用して、アクティベーションフローを作成できます。

手順4：最新のオーディエンス書き出しジョブ IDの取得（v2では不要） segment-export-id

バッチ宛先のアクティベーションフローを設定すると、スケジュールされたセグメンテーションジョブが24時間ごとに自動的に実行され始めます。

アドホックアクティベーションジョブを実行する前に、最新のオーディエンス書き出しジョブのIDを取得する必要があります。 このIDは、アドホックアクティベーションジョブリクエストで渡す必要があります。

すべてのオーディエンス書き出しジョブのリストを取得するには、ここで説明した手順に従います。

応答で、以下のスキーマプロパティを含む最初のレコードを探します。

"schema":{
   "name":"_xdm.context.profile"
}

オーディエンス書き出しジョブ IDは、次に示すようにid プロパティにあります。

手順5：アドホックアクティベーションジョブの実行 activation-job

Adobe Experience Platformは、スケジュールされたセグメント化ジョブを24時間ごとに1回実行します。 アドホックアクティベーション APIは、最新のセグメント化結果に基づいて実行されます。

アドホックアクティベーションジョブを実行する前に、オーディエンスのスケジュールされたオーディエンス書き出しジョブが完了していることを確認します。 アクティベーションフローのステータスを監視する方法については、宛先データフロー監視を参照してください。 例えば、アクティベーションデータフローに​Processing ステータスが表示されている場合は、アドホックアクティベーションジョブを実行して完全なファイルを書き出す前に、アクティベーションデータフローが終了するのを待ちます。

オーディエンスの書き出しジョブが完了したら、アクティベーションをトリガーできます。

リクエスト request

セグメント化サービス以外のオーディエンス（例：外部オーディエンスまたはカスタムアップロードオーディエンス ​）の場合は、外部オーディエンス IDではなく、リクエストでExperience Platformによって生成されたオーディエンス IDを指定する必要があります。 オーディエンス UIでオーディエンスの詳細ページを開くと、​ オーディエンスの概要パネル ​の上部に​ ID# ​と表示され、その後UUIDが表示されます。

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

プロパティ

説明

• destinationId1
• destinationId2

オーディエンスをアクティブ化する宛先インスタンスのID。 これらのIDは、Experience Platform UIから取得できます。「Destinations > Browse」タブに移動し、目的の宛先行をクリックして、右側のパネルで宛先IDを表示します。 詳しくは、宛先ワークスペースのドキュメント ​を参照してください。

• segmentId1
• segmentId2
• segmentId3

選択した宛先に対してアクティブ化するオーディエンスのID。 アドホック APIを使用して、Experience Platformで生成されたオーディエンスと、外部（カスタムアップロード）オーディエンスを書き出すことができます。 外部オーディエンスをアクティブ化する場合は、オーディエンス IDの代わりにシステム生成IDを使用します。 システムで生成されたIDは、オーディエンス UIのオーディエンス概要ビューで確認できます。
選択しないオーディエンス IDの {width="100" modal="regular"}
使用するシステム生成オーディエンス IDの {width="100" modal="regular"}

書き出しIDを使用したリクエスト request-export-ids

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

応答 response

応答が成功すると、HTTP ステータス 200が返されます。

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

API エラー処理 api-error-handling

Destination SDK API エンドポイントは、一般的な Experience Platform API エラーメッセージの原則に従います。Experience Platform トラブルシューティングガイドのAPI ステータスコード ​および​ リクエストヘッダーエラーを参照してください。

アドホックアクティベーション APIに固有のAPI エラーコードとメッセージ specific-error-messages

アドホックアクティベーション APIを使用する場合、このAPI エンドポイントに固有のエラーメッセージが表示される可能性があります。 表を確認して、それらの対処方法を確認します。

関連情報 related-information