以下是建議的工作流程,可驗證事件和目標對象上傳作業的健康狀態,並找出資料問題。
查看每項要求的整體狀態。成功的要求會包含
Status,其中code等於0(列舉值OK,HTTP 回應200 OK),並傳回IngestEventsResponse、IngestAudienceMembersResponse或RemoveAudienceMembersResponse。如果要求失敗,請修改要求以解決錯誤,然後再次傳送要求。
如果要求成功,請擷取回應的
request_id,以便在下一個步驟中擷取診斷資訊。等待 30 分鐘,然後針對每個成功的
request_id傳送RetrieveRequestStatus要求。定期為每個
request_id重複這個步驟,直到每個目的地的目的地狀態達到SUCCESS、PARTIAL_SUCCESS或FAILURE為止。使用指數輪詢演算法,在每次要求之間等待。請查看每個
RetrieveRequestStatusResponse,確認上傳作業正常運作,並找出資料問題。修正資料問題。
返回步驟 1 並重複執行,直到解決所有上傳問題。
提出要求
RetrieveRequestStatusRequest 需要單一 request_id 值。請為從成功擷取要求中擷取的每個要求 ID,分別傳送狀態要求。
授權
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錯誤。
輪詢策略
使用指數輪詢演算法定期傳送 RetrieveRequestStatusRequest,直到原始要求中每個目的地的 request_status 達到 SUCCESS、FAILURE 或 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 小時總時間上限前,提出最後一次要求 |
在輪詢延遲中加入少量的隨機時基誤差,避免多個用戶端同時重試,造成「驚群」問題。
查看回覆
RetrieveRequestStatusResponse 中的 request_status_per_destination 會針對相應擷取要求中的每個目的地,包含個別項目。
舉例來說,如果 IngestAudienceMembersRequest 的 destinations 清單包含 3 個項目,用於將資料傳送至 3 個不同的目標對象,則狀態回應的 request_status_per_destination 會包含 3 個項目 (每個目標對象一個項目)。
查看整體到達網頁狀態
首先,請檢查 request_status 欄位,判斷 Data Manager API 是否已完成處理 RequestStatusPerDestination 的 destination 資料。
request_status 的可能值如下:
PROCESSING:目的地資料仍在處理中。在這個階段,目的地不會填入警告和錯誤。SUCCESS:目的地要求處理作業已完成,未發生任何錯誤。查看處理期間標記的警告。FAILURE:目的地所有記錄因發生錯誤而失敗。查看警告和錯誤,判斷所有記錄失敗的原因。此外,請檢查處理期間是否出現警告。PARTIAL_SUCCESS:部分目的地記錄成功,但其他記錄因錯誤而失敗。檢查錯誤,找出部分記錄失敗的原因。並查看處理期間標記的警告。
查看各目的地的事件或目標對象狀態
檢查與攝入要求類型對應的狀態欄位。每個 RequestStatusPerDestination 只能設定下列其中一個欄位:
事件擷取狀態
如果要求是 IngestEventsRequest,系統會填入 events_ingestion_status 欄位。
查看 IngestEventStatus 的 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,確認收到的 Mobile ID 數量符合預期。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 或 FAILURE 時,系統會填入這些欄位。
warning_infoWarningInfo物件。其warning_counts欄位包含WarningCount物件清單。每個WarningCount都包含一個reason(含有警告類型) 和一個record_count(指出具有該警告類型的記錄數量)。即使整體目的地狀態為
SUCCESS,也請檢查warning_info。error_infoErrorInfo物件。其error_counts欄位包含ErrorCount物件清單。每個ErrorCount都包含一個reason,其中包含錯誤類型,以及一個record_count,指出因該類型錯誤而失敗的記錄數量。