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

概觀 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時，請牢記以下護欄。

分段考量事項 segmentation-considerations

Adobe Experience Platform每24小時執行一次排程的區段工作。 臨機啟動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

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

這包括進入啟用工作流程、選取您的對象、設定排程並啟用它們。 您可以使用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小時執行一次排程的區段工作。 臨機啟動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。 您可以導覽至​ 目的地 > 瀏覽 ​標籤，然後按一下所需的目的地列，在右側邊欄中叫出目的地ID，從Platform UI取得這些ID。 如需詳細資訊，請閱讀目的地工作區檔案。

• segmentId1
• segmentId2
• segmentId3

您要啟用至所選目的地的對象ID。 您可以使用臨機API匯出平台產生的對象以及外部（自訂上傳）對象。 啟用外部對象時，請使用系統產生的ID，而非對象ID。 您可以在對象UI的對象摘要檢視中找到系統產生的ID。
{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狀態碼和請求標頭錯誤。

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

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

相關資訊 related-information