傳送事件或目標對象成員的要求會以非同步方式處理。如果擷取成功,系統會傳回 request_id,表示要求符合所有規定,且已接受處理。不過,這並不代表要求中的記錄已成功處理。
請將傳回的 request_id 與 RetrieveRequestStatus 搭配使用,檢查上傳狀態並查看診斷資訊。
建議您按照下列工作流程,檢查要求狀態,並確認事件和目標對象上傳作業的健康狀態:
查看每項攝入要求的整體狀態。成功的要求會包含
Status,其中code等於0(列舉值OK,HTTP 回應200 OK),並傳回IngestEventsResponse、IngestAudienceMembersResponse或RemoveAudienceMembersResponse。如果要求失敗,請修改要求以解決錯誤,然後再次傳送要求。
如果要求成功,請擷取回應的
request_id,以便在下一個步驟中用來檢查處理狀態。等待 30 分鐘,然後為每個成功的
request_id傳送RetrieveRequestStatus要求。RetrieveRequestStatusRequest需要單一request_id值。針對從成功擷取要求中擷取的每個要求 ID,傳送個別狀態要求。定期為每個
request_id重複這個步驟,直到每個目的地的目的地狀態達到SUCCESS、PARTIAL_SUCCESS或FAILED。請按照建議的輪詢策略,在每次要求之間等待。請查看每個
RetrieveRequestStatusResponse,確認上傳作業正常運作,並找出資料問題。修正資料問題。
返回步驟 1 並重複執行,直到上傳內容的所有問題都解決為止。
查看整體目的地狀態
RetrieveRequestStatusResponse 中的 request_status_per_destination 包含對應攝入要求中每個目的地的個別項目。
舉例來說,如果 IngestAudienceMembersRequest 的 destinations 清單包含 3 個項目,用於將資料傳送至 3 個不同的目標對象,則狀態回應的 request_status_per_destination 會包含 3 個項目 (每個目標對象一個項目)。
檢查每個 RequestStatusPerDestination 的 request_status 欄位,判斷 Data Manager API 是否已完成該目的地的資料處理。
request_status 的可能值如下:
PROCESSING:目的地的資料仍在處理中。在這個階段,系統不會填入目的地的警告和錯誤。持續輪詢,直到狀態達到終端狀態。SUCCESS:目的地要求處理作業已完成,未發生任何錯誤。查看處理期間標記的警告。FAILED:目的地所有記錄因錯誤而失敗。查看警告和錯誤,判斷所有記錄失敗的原因。此外,請檢查處理期間標記的警告。PARTIAL_SUCCESS:目的地的部分記錄成功,但其他記錄因錯誤而失敗。檢查錯誤,找出部分記錄失敗的原因。並查看處理期間是否出現警告。
查看診斷結果
當目的地的 request_status 達到 SUCCESS、FAILED 或 PARTIAL_SUCCESS 時,請查看回應中的詳細診斷資訊,驗證計數並排解問題。
查看各目的地的事件或目標對象狀態
檢查與攝入要求類型對應的狀態欄位。每個 RequestStatusPerDestination 只能設定下列其中一個欄位:
事件擷取狀態
如果要求是 IngestEventsRequest,系統會填入 events_ingestion_status 欄位。
查看 IngestEventsStatus 的 record_count,確認收到的記錄總數符合預期。record_count 包含成功和失敗的記錄。
目標對象成員擷取狀態
如果要求是 IngestAudienceMembersRequest,系統會填入 audience_members_ingestion_status 欄位。以下是各類目標對象資料要檢查的 IngestAudienceMembersStatus 欄位。系統只會設定其中一個欄位。
composite_data_ingestion_status請查看
IngestCompositeDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。請查看
data_type_counts,確認 ID 數量符合預期。這份清單會列出DataType接收到的所有 ID (例如電子郵件地址、電話號碼、實際地址和 IP 位址)。如果要求包含足夠的記錄,
upload_match_rate_range會包含要求中記錄的媒合率範圍。google_user_id_data_ingestion_status查看
IngestGoogleUserIdDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
google_user_id_count,確認收到的 Google 使用者 ID 數量符合預期。mobile_data_ingestion_status請查看
IngestMobileDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
mobile_id_count,確認收到的數位身分證件數量符合預期。pair_data_ingestion_status查看
IngestPairDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
pair_id_count,確認收到的 PAIR ID 數量符合預期。partner_provided_id_data_ingestion_status查看
IngestPartnerProvidedIdDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。請查看
partner_provided_id_count,確認收到的合作夥伴提供 ID 數量符合預期。ppid_data_ingestion_status查看
IngestPpidDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
ppid_count,確認收到的 PPID 數量符合預期。user_data_ingestion_status查看
IngestUserDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
user_identifier_count,確認收到的使用者 ID 數量符合預期。如果要求包含足夠的記錄,
upload_match_rate_range會包含要求中記錄的媒合率範圍。user_id_data_ingestion_status查看
IngestUserIdDataStatus的record_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。查看
user_id_count,確認收到的使用者 ID 數量符合預期。
目標對象成員移除狀態
如果要求是 RemoveAudienceMembersRequest,系統會填入 audience_members_removal_status 欄位。以下是各類目標對象資料應檢查的 RemoveAudienceMembersStatus 欄位。系統只會設定其中一個欄位。
composite_data_removal_status- 複合資料的移除狀態
google_user_id_data_removal_status- Google 使用者 ID 資料的移除狀態
mobile_data_removal_status- 行動數據的移除狀態。
pair_data_removal_status- PAIR 資料的移除狀態。
partner_provided_id_data_removal_status- 合作夥伴提供的 ID 資料移除狀態
ppid_data_removal_status- PPID 資料的移除狀態。
user_data_removal_status- 使用者資料的移除狀態。
user_id_data_removal_status- 使用者 ID 資料的移除狀態
查看 record_count,確認收到的記錄總數符合預期。record_count 包含成功和失敗的記錄。
此外,請查看 user_identifier_count、mobile_id_count、pair_id_count、ppid_count、user_id_count、google_user_id_count 或 partner_provided_id_count,確認收到的 ID 總數。
如果是複合資料,請查看 data_type_counts,確認 ID 數量符合預期。這份清單會列出 DataType 接收到的所有 ID (例如電子郵件地址、電話號碼、實際地址和 IP 位址)。
查看警告和錯誤
除了目的地和要求類型的狀態欄位外,RetrieveRequestStatusResponse 還包含要求的警告和錯誤細目。
如果出現錯誤,代表 API 完全拒絕記錄。
警告表示 API 未拒絕記錄,但必須忽略記錄的部分資料。
舉例來說,如果 Event 包含加密的 UserIdentifier 資料和 AdIdentifiers (例如 gclid),且 UserIdentifier 資料無法解密,Data Manager API 仍會使用 AdIdentifiers 處理記錄,但會傳回警告 PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR。
不過,如果 Event 不含 AdIdentifiers,且 UserIdentifier 資料無法解密,Data Manager API 會拒絕整筆記錄,並回報 PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR 錯誤,因為有效的 Event 必須至少包含 ad_identifiers 或 user_data。
以下是包含警告和錯誤資訊的回應欄位。當整體目的地狀態達到 SUCCESS、PARTIAL_SUCCESS 或 FAILED 時,系統會填入這些欄位。
warning_infoWarningInfo物件。其warning_counts欄位包含WarningCount物件清單。每個WarningCount包含:reason:警告類型。record_count:出現該類型警告的記錄數量。record_indices:原始要求中具有該類型警告的記錄索引。請參閱「查看受影響的記錄」。
即使整體目的地狀態為
SUCCESS,也請檢查warning_info。error_infoErrorInfo物件。其error_counts欄位包含ErrorCount物件清單。每個ErrorCount包含:reason:錯誤類型。record_count:因該類型錯誤而失敗的記錄數量。record_indices:原始要求中因該類型錯誤而失敗的記錄索引。請參閱「查看受影響的記錄」。
檢查受影響的記錄
請使用每個 WarningCount 和 ErrorCount 的 record_indices,找出擷取要求中出現警告或錯誤的確切記錄。
record_indices 中的每個值都是原始要求中記錄的位置 (從 0 開始):
如果是
IngestEventsRequest,索引是指事件在要求events清單中的位置。如果是
IngestAudienceMembersRequest,索引是指目標對象成員在要求audience_members清單中的位置。
舉例來說,record_indices 值為 0 代表要求中的第一個事件或目標對象成員。
分析 record_indices 時,請注意下列事項:
系統會依目的地回報索引。如果要求有多個目的地,每個
RequestStatusPerDestination都會回報該目的地有警告或錯誤的記錄索引。同一筆記錄可以出現在多個RequestStatusPerDestination中。一筆記錄可能有多個原因。舉例來說,一筆記錄可能同時有錯誤和警告,或有多種類型的警告。如要找出特定記錄的所有問題,請檢查目的地的每個
WarningCount和ErrorCount。
以下是 IngestEventsRequest 的 RetrieveRequestStatusResponse 範例,其中包含五個事件和一個目的地。第一個事件 (索引 0) 和第四個事件 (索引 3) 失敗,因為交易 ID 已上傳,而第三個事件 (索引 2) 已處理,但具有未預先定義的自訂變數值。
{
"requestStatusPerDestination": [
{
"destination": {
"operatingAccount": {
"accountType": "GOOGLE_ADS",
"accountId": "1234567890"
},
"productDestinationId": "123456789"
},
"requestStatus": "PARTIAL_SUCCESS",
"eventsIngestionStatus": {
"recordCount": "5"
},
"errorInfo": {
"errorCounts": [
{
"recordCount": "2",
"reason": "PROCESSING_ERROR_REASON_DUPLICATE_TRANSACTION_ID",
"recordIndices": [0, 3]
}
]
},
"warningInfo": {
"warningCounts": [
{
"recordCount": "1",
"reason": "PROCESSING_WARNING_REASON_CUSTOM_VARIABLE_NOT_PREDEFINED",
"recordIndices": [2]
}
]
}
}
]
}
如要修正記錄,請按照下列步驟操作:
針對每個
ErrorCount和WarningCount,使用record_indices查詢原始要求中的對應記錄。請使用
reason判斷如何修正每筆記錄。如需各原因的說明,請參閱ProcessingErrorReason和ProcessingWarningReason。傳送新的攝入要求,其中只包含修正後的記錄。請勿重新傳送已成功傳送的記錄,否則可能會導致資料重複或發生其他錯誤。
輪詢策略
使用指數輪詢演算法定期傳送 RetrieveRequestStatusRequest,直到原始要求中每個目的地的 request_status 達到 SUCCESS、FAILED 或 PARTIAL_SUCCESS 為止。這項作業最多可能需要 24 小時,但 Data Manager API 最快可在 30 分鐘內完成處理部分要求。
以下是合理的初始等待時間和重試設定範例,可平衡活躍度和配額用量:
| 設定 | 值 |
|---|---|
| 首次診斷要求前的等待時間 (分鐘) | 30 |
| 輪詢時間調節係數 | 1.3 |
| 輪詢時間上限 (分鐘) | 60 (1 小時) |
| 總時間上限 (分鐘) | 1440 (24 小時) |
以下是這項設定的要求序列和經過時間:
圖表

資料
| 嘗試 | 提出擷取要求後經過的時間 (hh:mm) | 嘗試前延遲 | 附註 |
|---|---|---|---|
| 1 | 00:30 | 30.0 分鐘 | 首先,請確認狀態是否可用 |
| 2 | 01:09 | 39.0 分鐘 | |
| 3 | 01:59 | 50.7 分鐘 | |
| 4 | 02:59 | 60.0 分鐘 | 延遲時間上限現為 1 小時 |
| 5 | 03:59 | 60.0 分鐘 | |
| 6 | 04:59 | 60.0 分鐘 | |
| 7 | 05:59 | 60.0 分鐘 | |
| 8 | 06:59 | 60.0 分鐘 | |
| 9 | 07:59 | 60.0 分鐘 | |
| 10 | 08:59 | 60.0 分鐘 | |
| 11 | 09:59 | 60.0 分鐘 | |
| 12 | 10:59 | 60.0 分鐘 | |
| 13 | 11:59 | 60.0 分鐘 | 12 小時 |
| 14 | 12:59 | 60.0 分鐘 | |
| 15 | 13:59 | 60.0 分鐘 | |
| 16 | 14:59 | 60.0 分鐘 | |
| 17 | 15:59 | 60.0 分鐘 | |
| 18 | 16:59 | 60.0 分鐘 | |
| 19 | 17:59 | 60.0 分鐘 | |
| 20 | 18:59 | 60.0 分鐘 | |
| 21 | 19:59 | 60.0 分鐘 | |
| 22 | 20:59 | 60.0 分鐘 | |
| 23 | 21:59 | 60.0 分鐘 | |
| 24 | 22:59 | 60.0 分鐘 | |
| 25 | 23:59 | 60.0 分鐘 | 24 小時總時間上限前的最後一次要求 |
在輪詢延遲中加入少量隨機時基誤差,避免多個用戶端同時重試,造成「驚群效應」問題。
授權規定
RetrieveRequestStatusRequest 不接受目的地帳戶或要求標頭。而是由 Data Manager API 根據與 request_id 相關聯的原始擷取要求,找出目的地,並驗證呼叫端是否有權存取每個 Destination 上的 operating_account。
如要檢查要求狀態,RetrieveRequestStatusRequest 中使用的憑證必須符合下列要求,才能用於原始擷取要求中各個目的地的 operating_account:
相同的存取路徑:憑證必須使用原始擷取要求中指定的完全相同存取路徑,才能存取每個
operating_account。舉例來說,如果 Google Ads
operating_account的擷取要求將上層管理員帳戶指定為login_account,則憑證也必須透過同一個管理員帳戶存取operating_account。即使與憑證相關聯的 Google 帳戶可直接存取子operating_account,但如果該帳戶無法透過擷取期間指定的login_account管理員帳戶存取,要求仍會失敗,並傳回PERMISSION_DENIED錯誤。足夠的存取層級:與憑證相關聯的 Google 帳戶必須具備存取層級或角色,有權將資料擷取至
operating_account。舉例來說,在 Google Ads 中,Google 帳戶必須具備管理員或標準存取層級。如果要求使用的帳戶憑證存取層級為「唯讀」,則會失敗並傳回
PERMISSION_DENIED錯誤。