透過臨機啟動API依需求啟用批次目的地的對象

IMPORTANT
完成Beta階段後,ad-hoc activation API現在可供所有Experience Platform客戶普遍使用(GA)。 在GA版本中,API已升級至版本2。 步驟4 (取得最新的對象匯出工作ID)不再是必要步驟,因為API不再需要匯出工作ID。
如需詳細資訊,請參閱本教學課程下方執行臨機操作啟動工作

概觀 overview

臨機啟動API可讓行銷人員針對需要立即啟動的情況,以快速且有效率的方式以程式設計方式將對象啟動至目的地。

使用臨機啟動API將完整檔案匯出至您想要的檔案接收系統。 僅批次檔案型目的地支援隨選對象啟用。

下圖說明透過臨機啟動API啟動對象的端對端工作流程,包括每24小時在Platform中發生的細分工作。

臨機啟動

使用案例 use-cases

Flash銷售或促銷

一家線上零售商正準備進行限量閃購,並希望在短時間內通知客戶。 透過Experience Platform臨機啟動API,行銷團隊可以隨選匯出對象,並快速傳送促銷電子郵件給客戶群。

最新事件或突發新聞

飯店期望在接下來的幾天內遇到惡劣天氣,而團隊想要快速通知到來的客人,以便他們做出相應的計畫。 行銷團隊可以使用Experience PlatformAd Hoc Activation API來隨選匯出受眾,並通知來賓。

整合測試

IT管理員可使用Experience Platform臨機啟動API來隨選匯出對象,以便測試其與Adobe Experience Platform的自訂整合,並確保一切都正常運作。

護欄 guardrails

使用臨機啟動API時,請牢記以下護欄。

  • 目前,每個隨選啟動工作最多可啟動80個對象。 嘗試為每個工作啟用超過80個對象會導致工作失敗。 未來版本可能會對此行為有所變更。
  • 臨機啟動工作無法與排程的對象匯出工作並行執行。 在執行臨機啟動工作之前,請確定已排程的對象匯出工作已完成。 如需如何監視啟用流程狀態的資訊,請參閱目的地資料流程監視。 例如,如果您的啟動資料流顯示​ 正在處理 ​狀態,請等待它完成後再執行臨機操作啟動工作。
  • 請勿對每個對象執行多個同時的臨機啟動工作。

分段考量事項 segmentation-considerations

Adobe Experience Platform每24小時執行一次排程的區段工作。 臨機啟動API會根據最新的分段結果執行。

步驟1:必要條件 prerequisites

呼叫Adobe Experience Platform API之前,請確定您符合下列必要條件:

  • 您擁有可存取Adobe Experience Platform的組織帳戶。
  • 您的Experience Platform帳戶已針對Adobe Experience Platform API產品設定檔啟用developeruser角色。 請連絡您的Admin Console管理員,為您的帳戶啟用這些角色。
  • 您有Adobe ID。 如果您沒有Adobe ID,請前往Adobe Developer Console並建立新帳戶。

步驟2:收集認證 credentials

若要呼叫Platform API,您必須先完成驗證教學課程。 完成驗證教學課程,在所有Experience Platform API呼叫中提供每個必要標題的值,如下所示:

  • 授權:持有人{ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Experience Platform中的資源可以隔離到特定的虛擬沙箱。 在對Platform API的請求中,您可以指定將執行作業的沙箱名稱和ID。 這些是選用引數。

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
如需Experience Platform中沙箱的詳細資訊,請參閱沙箱概觀檔案

包含裝載(POST、PUT、PATCH)的所有請求都需要額外的媒體型別標頭:

  • Content-Type: application/json

步驟3:在Platform UI中建立啟動流程 activation-flow

您必須先在平台UI中針對所選目的地設定啟用流程,才能透過臨機啟動API啟用對象。

這包括進入啟用工作流程、選取您的對象、設定排程並啟用它們。 您可以使用UI或API來建立啟用流程:

步驟4:取得最新的對象匯出作業ID (v2中不需要) segment-export-id

IMPORTANT
在臨機啟動API v2中,您不需要取得最新的對象匯出工作ID。 您可以略過此步驟,繼續下一個步驟。

當您為批次目的地設定啟動流程後,排程的分段工作會每24小時自動執行一次。

您必須先取得最新對象匯出工作的ID,才能執行隨選啟動工作。 您必須在臨機啟動工作請求中傳遞此ID。

依照這裡說明的指示,擷取所有對象匯出工作的清單。

在回應中,尋找包含下列結構描述屬性的第一個記錄。

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

對象匯出工作ID位於id屬性中,如下所示。

對象匯出工作ID

步驟5:執行臨機操作啟動工作 activation-job

Adobe Experience Platform每24小時執行一次排程的區段工作。 臨機啟動API會根據最新的分段結果執行。

IMPORTANT
請注意下列一次性限制:在執行臨機操作啟用工作之前,請確定根據您在步驟3 — 在Platform UI中建立啟用流程中所設定的排程,從對象首次啟用的那一刻起已過去至少20分鐘。

在執行臨機啟動工作之前,請確定您對象的排程對象匯出工作已完成。 如需如何監視啟用流程狀態的資訊,請參閱目的地資料流程監視。 例如,如果您的啟動資料流顯示​ 正在處理 ​狀態,請等待它完成後再執行臨機操作啟動工作以匯出完整檔案。

對象匯出工作完成後,您可以觸發啟動。

NOTE
目前,每個隨選啟動工作最多可啟動80個對象。 嘗試為每個工作啟用超過80個對象會導致工作失敗。 未來版本可能會對此行為有所變更。

請求 request

IMPORTANT
您必須在要求中加入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
您想要啟用對象之目的地執行個體的ID。 您可以導覽至​ 目的地 > 瀏覽 ​標籤,然後按一下所需的目的地列,在右側邊欄中叫出目的地ID,從Platform UI取得這些ID。 如需詳細資訊,請閱讀目的地工作區檔案
  • segmentId1
  • segmentId2
  • segmentId3
您要啟用至所選目的地的對象ID。 您可以使用臨機API匯出平台產生的對象以及外部(自訂上傳)對象。 啟用外部對象時,請使用系統產生的ID,而非對象ID。 您可以在對象UI的對象摘要檢視中找到系統產生的ID。
檢視不應選取的對象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"
   ]
}
屬性
說明
  • destinationId1
  • destinationId2
您想要啟用對象之目的地執行個體的ID。 您可以導覽至​ 目的地 > 瀏覽 ​標籤,然後按一下所需的目的地列,在右側邊欄中叫出目的地ID,從Platform UI取得這些ID。 如需詳細資訊,請閱讀目的地工作區檔案
  • segmentId1
  • segmentId2
  • segmentId3
您要啟用至所選目的地的對象ID。
  • exportId1
對象匯出作業的回應中傳回的ID。 請參閱步驟4:取得最新的對象匯出工作ID,瞭解如何尋找此ID的說明。

回應 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
已啟動受眾的ID。
order
對象啟用的目的地識別碼。
statusURL
啟動流程的狀態URL。 您可以使用流量服務API來追蹤流量進度。

API錯誤處理 api-error-handling

Destination SDK API端點遵循一般Experience Platform API錯誤訊息原則。 請參閱Platform疑難排解指南中的API狀態碼請求標頭錯誤

Ad Hoc Activation API專屬的API錯誤代碼和訊息 specific-error-messages

使用臨機啟動API時,您可能會遇到特定於此API端點的錯誤訊息。 請檢閱表格以瞭解如何在它們出現時解決它們。

錯誤訊息
解決方法
已對執行識別碼為flow run ID的訂單dataflow ID的對象segment ID執行中
此錯誤訊息表示對象目前正在進行臨機啟動流程。 再次觸發啟動工作前,請等候工作完成。
區段<segment name>不是此資料流的一部分或超出排程範圍!
此錯誤訊息指出您選取要啟用的對象未對應至資料流,或是為對象設定的啟用排程已過期或尚未開始。 檢查對象是否確實對應至資料流,並確認對象啟用排程與目前日期重疊。

相關資訊 related-information

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6