透過臨機啟動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之前，請確定您符合下列必要條件：
- 您擁有可存取Adobe Experience Platform的組織帳戶。
- 您的Experience Platform帳戶已針對Adobe Experience Platform API產品設定檔啟用
developer和user角色。 請連絡您的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}
包含裝載(POST、PUT、PATCH)的所有請求都需要額外的媒體型別標頭：
- Content-Type：
application/json
步驟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
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"
]
}
}'
destinationId1destinationId2
segmentId1segmentId2segmentId3
使用匯出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"
]
}
destinationId1destinationId2
segmentId1segmentId2segmentId3
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端點的錯誤訊息。 請檢閱表格以瞭解如何在它們出現時解決它們。
flow run ID的訂單dataflow ID的對象segment ID執行中<segment name>不是此資料流的一部分或超出排程範圍！