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

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

概觀 overview

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

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

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

ad-hoc-activation

使用案例 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帳戶具有 developeruser Adobe Experience Platform API產品設定檔啟用的角色。 連絡您的 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
請注意下列一次性限制:在執行臨機操作啟動工作之前,請確定根據您設定的排程,從對象首次啟動之時起已過去至少20分鐘 步驟3 — 在Platform UI中建立啟動流程.

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

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

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

請求 request

IMPORTANT
必須包含 Accept: application/vnd.adobe.adhoc.activation+json; version=2 標頭,以便使用Ad Hoc Activation 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。 您可以導覽至,從Platform UI取得這些ID 目的地 > 瀏覽 索引標籤,然後按一下所需的目的地列,以在右側邊欄中顯示目的地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。 您可以導覽至,從Platform UI取得這些ID 目的地 > 瀏覽 索引標籤,然後按一下所需的目的地列,以在右側邊欄中顯示目的地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錯誤訊息原則。 請參閱 API狀態代碼請求標頭錯誤 (位於平台疑難排解指南中)。

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

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

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

相關資訊 related-information

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