Adobe Target Bulk Profile Update API

Last update: Tue Oct 28 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
APIs/SDKs

建立對象：

開發人員

Adobe Target Bulk Profile Update API可讓您使用批次檔案，大量更新多個網站訪客的使用者設定檔。

使用Bulk Profile Update API，您可以方便地將許多使用者的詳細訪客設定檔資料以設定檔引數的形式從任何外部來源傳送到Target。外部來源可能包括客戶關係管理(CRM)或銷售點(POS)系統，這些通常無法在網頁上使用。

版本

URL範例

功能

http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/profile/batchUpdate

僅支援大量設定檔更新。

http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate

如果找不到，請建立設定檔。
每列狀態更新。

NOTE

Bulk Profile Update API的版本2 (v2)是目前的版本。不過，Target仍持續支援版本1 (v1)。

如果您的Target實作使用Experience Cloud ID (ECID)作為匿名訪客的其中一個設定檔識別碼，請勿使用pcId作為版本2 (v2)批次檔案中的索引鍵。將pcId與Bulk Profile Update API的v2搭配使用，僅適用於不依賴ECID的獨立式Target實作。
如果您的實作使用ECID來識別設定檔，而且您想要使用pcId做為批次檔案中的金鑰，請使用API的第1版(v1)。
如果您的實作使用thirdPartyId來識別設定檔，請使用包含thirdPartyId的API版本2 (v2)作為金鑰。

Bulk Profile Update API的優點

設定檔屬性的數量不限。
透過網站傳送的設定檔屬性可以透過API更新，反之亦然。

注意事項

批次檔的大小必須小於 50 MB。此外，每次上傳的總列數不得超過 500,000 列。
更新通常在一小時內發生，但可能需要長達24小時的時間才會反映。
您可以上傳後續批次中超過24小時期間的一或多列數量沒有限制。不過，在上班時間可以節流汲取程序，以確保其他程序的執行效率。
對相同的thirdPartyIds採用連續v2批次更新呼叫，且其中不需使用mbox呼叫，會覆寫第一次批次更新呼叫所更新的屬性。
Adobe不保證100%的批次設定檔資料將上線並保留在Target中，因此可用於目標定位。在目前的設計中，小部分資料（最多佔大型生產批次的0.1%）有可能不會上線或保留。

批次檔案

若要大量更新設定檔資料，請建立批次檔案。批次檔案是文字檔，其值由逗號分隔，類似於以下範例檔案。

\ batch=pcId,param1,param2,param3,param4\ 123,value1\ 124,value1,value4\ 125,value2\ 126,value1,value2,value3,value4\

NOTE

batch=引數為必要項，必須在檔案開頭指定。

您在Target伺服器的POST呼叫中參考此檔案，以處理該檔案。建立批次檔案時，請考量下列事項：

檔案的第一列必須指定欄標題。
第一個標頭應該是pcId或thirdPartyId。不支援Marketing Cloud visitor ID。 pcId是Target產生的訪客ID。 thirdPartyId是使用者端應用程式所指定的ID，它是透過mbox呼叫傳遞至Target做為mbox3rdPartyId。它必須在這裡稱為thirdPartyId。
基於安全理由，您在批次檔案中指定的引數和值必須使用UTF-8進行URL編碼。引數和值可以轉送至其他邊緣節點，以透過HTTP請求處理。
引數只能使用paramName格式。引數在Target中顯示為profile.paramName。
如果您使用Bulk Profile Update API v2，則不需要為每個pcId指定所有引數值。已為pcId中找不到的任何mbox3rdPartyId或Target建立設定檔。如果您使用v1，則不會為遺失的pcIds或mbox3rdPartyIds建立設定檔。如需詳細資訊，請參閱下列中的 Bulk Profile Update API處理空白值。
批次檔的大小必須小於 50 MB。此外，總列數不應超過500,000。此限制可確保伺服器不會因太多請求而泛濫。
您可以傳送多個檔案。不過，您一天內傳送之所有檔案的總列數，每個使用者端不應超過100萬列。
您可以上傳的屬性數目沒有限制。不過，外部設定檔資料的總計大小不得超過64 KB，其中包括客戶屬性、設定檔API、In-Mbox設定檔引數以及設定檔指令碼輸出。
引數和值區分大小寫。

HTTP POST要求

向Target個邊緣伺服器發出HTTP POST要求以處理檔案。以下為使用curl命令建立batch.txt檔案的HTTP POST要求範例：

\ curl -X POST --data-binary @BATCH.TXT http\://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate\

其中:

BATCH.TXT是檔案名稱。 CLIENTCODE是Target使用者端代碼。

如果您不知道使用者端代碼，請在Target使用者介面中按一下Administration > Implementation。使用者端代碼會顯示在Account Details區段中。

檢查回應

設定檔API會傳回批次的提交狀態以進行處理，連結「batchStatus」底下至顯示特定批次工作整體狀態的其他URL。

範例API回應

以下程式碼片段為設定檔API回應的範例：

<response>
    <success>true</success>
    <batchStatus>http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383</batchStatus>
    <message>Batch submitted for processing</message>
</response>

如果發生錯誤，回應會包含success=false以及錯誤的詳細訊息。

預設批次狀態回應

按一下上述batchStatus URL連結時，成功的預設回應如下所示：

<response><batchId>demo4-1701473848678-13029383</batchId><status>complete</status><batchSize>1</batchSize></response>

狀態列位的預期值為：

狀態

詳細資料

complete

設定檔批次更新請求已成功完成。

incomplete

設定檔批次更新請求仍在處理中，尚未完成。

stuck

設定檔批次更新請求卡住，無法完成。

詳細批次狀態URL回應

將引數showDetails=true傳遞至上述batchStatus URL，即可擷取更詳細的回應。

例如：

http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383&showDetails=true

詳細回應

<response>
    <batchId>demo4-1701473848678-13029383</batchId>
    <status>complete</status>
    <batchSize>1</batchSize>
    <consumedCount>1</consumedCount>
    <successfulUpdates>1</successfulUpdates>
    <profilesNotFound>0</profilesNotFound>
    <failedUpdates>0</failedUpdates>
</response>

處理Bulk Profile Update API中的空白值 empty

使用Target Bulk Profile Update API （v1或v2）時，請務必瞭解系統如何處理空的引數或屬性值。

預期行為

為現有引數或屬性傳送空白值（「」、null或缺少欄位）不會重設或刪除設定檔存放區中的這些值。這是刻意設計。

忽略空值： API會在處理期間篩選出空值，以避免不必要或無意義的更新。
不清除現有資料：如果引數已經有值，傳送空白值會維持不變。
略過僅限空白的批次：如果批次只包含空白或Null值，則會完全忽略該批次，並且不會套用任何更新。

其他附註

此行為同時適用於Bulk Profile Update API的v1和v2。

嘗試傳送空白值來清除或移除屬性沒有效果。

已規劃為未來版本的API (v3)支援明確屬性移除，但目前尚未提供。

recommendation-more-help

6906415f-169c-422b-89d3-7118e147c4e3