アドホックアクティベーション APIを使用してオンデマンドでオーディエンスをアクティベーション

概要 overview

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

アドホックアクティベーション APIを使用して、オーディエンスをオンデマンドでアクティベートし、​ バッチファイルベースの宛先に、v4からストリーミングおよび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とのカスタム統合をテストして、すべてが正しく動作していることを確認できます。

ストリーミング宛先用オーディエンスの更新 audience-refresh-streaming

ストリーミングまたはAPI ベースの宛先は、Adobe Experience Platformから受信したオーディエンスメンバーシップにTime-to-Live （TTL）を適用します。 そのTTLが宛先側で期限切れになると、以前に適格であったプロファイルは、Experience Platformで適格のままであっても、非アクティブとして扱われます。 マーケティング部門は、アドホックアクティベーション APIのv4を使用して、次回のスケジュールされた更新を待つことなく、オーディエンスの現在のメンバーシップをオンデマンドで再送信できます。 このチュートリアルでは、後述する​ アドホックアクティベーション実行のトリガーを参照してください。

ガードレール 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）を含むすべてのリクエストには、メディアのタイプを指定する以下のような追加ヘッダーが必要です。

API リファレンスドキュメント api-reference-documentation

このチュートリアルに含まれるすべての API 操作について、付属リファレンスドキュメントが用意されています。 ​ アドホックアクティベーション API リファレンス ​を参照してください。

手順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は、最新のセグメント化結果に基づいて実行されます。

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

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

リクエスト 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から取得できます。「宛先 > 参照」タブに移動し、目的の宛先行をクリックして、右側のパネルで宛先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 エンドポイントに固有のエラーメッセージが表示される可能性があります。 表を確認して、それらの対処方法を確認します。

（Beta）トリガーとアドホックアクティベーションの実行 streaming-destinations

アドホックアクティベーション APIのv4を使用して、ストリーミングまたはAPI ベースの宛先に対するオーディエンスのオンデマンドのフルメンバーシップ更新である​ 今すぐアクティベート ​をトリガーします。

多くのストリーミングおよびAPI ベースの宛先は、有効期間（TTL）をAdobe Experience Platformから受け取るオーディエンスメンバーシップに適用します。 そのTTLが宛先側で期限切れになると、以前に適格であったプロファイルは、Experience Platformで適格のままであっても、非アクティブとして扱われます。 v4 アドホックアクティベーションの実行をトリガーすると、次にスケジュールされた更新を待たずに、既存のストリーミングアクティベーションパイプラインを通じて現在適格なすべてのプロファイルを再送信できます。

Experience Platform UIからこの更新をトリガーすることもできます。 ​ ストリーミング宛先に対して今すぐアクティブ化をお読みください。

ストリーミングガードレール streaming-guardrails

ストリーミング宛先へのアドホックアクティベーションでは、次の制限が適用されます。

ストリーミングリクエスト streaming-request

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}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

ストリーミング応答 streaming-response

応答が成功すると、HTTP ステータス 202 （Accepted）が返され、リクエストされたオーディエンスごとに1つのストリーミングジョブが作成されます。

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

過去24時間以内にこのデータフローに対して同じオーディエンスが既にトリガーされている場合、リクエストはHTTP 409とRetry-After ヘッダーで拒否され、再試行できるまでの時間を示します。

関連情報 related-information