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

概要 overview

アドホックアクティベーション API を使用すると、マーケターは、即時にアクティベーションが必要な状況で、宛先へのオーディエンスオーディエンスをプログラムによってすばやく効率的にアクティブ化できます。

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

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

ユースケース use-cases

Flashの販売またはプロモーション

オンライン小売業者は、限定フラッシュセールを準備しており、顧客に短い通知で通知したいと考えています。 Experience Platformアドホックアクティベーション API を通じて、マーケティングチームはオーディエンスをオンデマンドで書き出し、プロモーションメールをすばやく顧客ベースに送信できます。

現在のイベントまたは最新ニュース

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

統合テスト

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

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

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

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

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

アドホックアクティベーション API を通じてオーディエンスをアクティブ化する前に、まず、選択した宛先の 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

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。 Platform UI からこれらの ID を取得するには、「宛先/参照 タブに移動し、目的の宛先行をクリックして、右側のパネルに宛先 ID を表示します。 詳しくは、 宛先ワークスペードキュメントを参照してください。

• segmentId1
• segmentId2
• segmentId3

選択した宛先に対してアクティブ化するオーディエンスの ID。 アドホック API を使用して、Platform で生成されたオーディエンスと外部（カスタムアップロード）オーディエンスを書き出すことができます。 外部オーディエンスをアクティブ化する場合は、オーディエンス ID ではなく、システムで生成された ID を使用します。 システム生成 ID は、オーディエンス UI のオーディエンスの概要ビューで確認できます。
{width="100" modal="regular"}
{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 エラーメッセージの原則に従います。Platform トラブルシューティングガイドの API ステータスコードおよびリクエストヘッダーエラーを参照してください。

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

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

関連情報 related-information