診斷

以下是建議的工作流程,可驗證事件和目標對象上傳作業的健康狀態,並找出資料問題。

  1. 發出要求,傳送事件,或傳送/移除目標對象成員。

  2. 查看每項要求的整體狀態。成功的要求會包含 Status,其中 code 等於 0 (列舉值 OK,HTTP 回應 200 OK),並傳回 IngestEventsResponse、IngestAudienceMembersResponse 或 RemoveAudienceMembersResponse。

    如果要求失敗,請修改要求以解決錯誤,然後再次傳送要求。

    如果要求成功,請擷取回應的 request_id,以便在下一個步驟中擷取診斷資訊。

  3. 等待 30 分鐘,然後針對每個成功的 request_id 傳送 RetrieveRequestStatus 要求。

    定期為每個 request_id 重複這個步驟,直到每個目的地的目的地狀態達到 SUCCESS、PARTIAL_SUCCESS 或 FAILURE 為止。使用指數輪詢演算法,在每次要求之間等待。

  4. 請查看每個 RetrieveRequestStatusResponse,確認上傳作業正常運作,並找出資料問題。

  5. 修正資料問題。

  6. 返回步驟 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_info

WarningInfo 物件。其 warning_counts 欄位包含 WarningCount 物件清單。每個 WarningCount 都包含一個 reason (含有警告類型) 和一個 record_count (指出具有該警告類型的記錄數量)。

即使整體目的地狀態為SUCCESS,也請檢查warning_info。

error_info

ErrorInfo 物件。其 error_counts 欄位包含 ErrorCount 物件清單。每個 ErrorCount 都包含一個 reason,其中包含錯誤類型,以及一個 record_count,指出因該類型錯誤而失敗的記錄數量。