アドホックアクティベーション 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 を使用する場合は、次のガードレールに注意してください。
- 現在、各アドホックアクティベーションジョブは、最大 80 個のオーディエンスをアクティベートできます。 1 つのジョブにつき 80 個を超えるオーディエンスをアクティベートしようとすると、ジョブが失敗します。 この動作は、今後のリリースで変更される可能性があります。
- アドホックアクティベーションジョブを、スケジュール済みと並行して実行することはできません オーディエンス書き出しジョブ. アドホックアクティベーションジョブを実行する前に、スケジュールされたオーディエンス書き出しジョブが完了していることを確認します。 参照: 宛先データフローの監視 アクティブ化フローのステータスの監視方法について説明します。 例えば、アクティベーションデータフローにが表示されている場合は次のようになります。 処理 ステータス。アドホックアクティベーションジョブを実行する前に、完了するまで待ちます。
- オーディエンスごとに複数のアドホックアクティベーションジョブを同時に実行しないでください。
セグメント化に関する考慮事項 segmentation-considerations
Adobe Experience Platformは、スケジュールされたセグメント化ジョブを 24 時間ごとに 1 回実行します。 アドホックアクティベーション API は、最新のセグメント化結果に基づいて実行されます。
手順 1:前提条件 prerequisites
Adobe Experience Platform API を呼び出す前に、次の前提条件を満たしていることを確認してください。
- Adobe Experience Platformにアクセスできる組織アカウントがある。
- お使いのExperience Platformアカウントには、
developer
およびuser
Adobe Experience Platform API 製品プロファイルに対して有効になっている役割。 に連絡してください Admin Console 管理者:アカウントでこれらの役割を有効にします。 - Adobe IDがある。 Adobe IDがない場合は、 Adobe Developer コンソール 新しいアカウントを作成します。
手順 2:資格情報の収集 credentials
Platform API への呼び出しを実行する前に、認証に関するチュートリアルを完了する必要があります。認証に関するチュートリアルを完了すると、すべての Experience Platform API 呼び出しで使用する、以下のような各必須ヘッダーの値が提供されます。
- Authorization: Bearer
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Experience Platform のリソースは、特定の仮想サンドボックスに分離することができます。Platform API へのリクエストでは、操作を実行するサンドボックスの名前と ID を指定できます。次に、オプションのパラメーターを示します。
- x-sandbox-name:
{SANDBOX_NAME}
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、メディアのタイプを指定する以下のような追加ヘッダーが必要です。
- Content-Type:
application/json
手順 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
Accept: application/vnd.adobe.adhoc.activation+json; version=2
アドホックアクティベーション API の v2 を使用するためのリクエストのヘッダー。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
segmentId1
segmentId2
segmentId3
![選択すべきでないオーディエンス ID の表示。](./media_1f7564521e8c25c21b74e23aedbdc5c1162b2918d.png?width=750&format=png&optimize=medium)
![使用する必要があるシステム生成オーディエンス ID の表示。](./media_1c92937e1c798138ceea5e9cfb14c2305b25d3f5a.png?width=750&format=png&optimize=medium)
書き出し 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"
]
}
destinationId1
destinationId2
segmentId1
segmentId2
segmentId3
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"
}
]
}
segment
order
statusURL
API エラー処理 api-error-handling
Destination SDK API エンドポイントは、一般的な Experience Platform API エラーメッセージの原則に従います。Platform トラブルシューティングガイドの API ステータスコードおよびリクエストヘッダーエラーを参照してください。
アドホックアクティベーション API に固有の API エラーコードとメッセージ specific-error-messages
アドホックアクティベーション API を使用する場合、この API エンドポイントに固有のエラーメッセージが表示される場合があります。 テーブルを確認して、表示されたときに対処する方法を理解します。
segment ID
注文 dataflow ID
実行 id を使用 flow run ID
<segment name>
はこのデータフローの一部ではないか、スケジュール範囲外です。