診斷

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

  1. 發出要求來傳送活動,或是傳送/移除目標對象成員

  2. 查看每項要求的整體狀態。如果要求成功,Statuscode 會等於 0 (列舉值 OK,HTTP 回應 200 OK),並傳回 IngestEventsResponseIngestAudienceMembersResponseRemoveAudienceMembersResponse

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

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

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

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

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

  5. 修正資料問題。

  6. 返回步驟 1 並重複操作,直到解決所有上傳問題為止。

提出要求

RetrieveRequestStatusRequest 必須是單一 request_id 值。針對您從成功擷取要求中擷取的每個要求 ID,分別傳送狀態要求。

使用指數輪詢演算法定期傳送 RetrieveRequestStatusRequest,直到原始要求中的每個目的地都達到 request_status SUCCESSFAILUREPARTIAL_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 會為對應的擷取要求中的每個目的地,分別包含一個項目。

舉例來說,如果 IngestAudienceMembersRequestdestinations 清單包含 3 個項目,可將資料傳送至 3 個不同的目標對象,則狀態回應的 request_status_per_destination 會包含 3 個項目 (每個目標對象各 1 個項目)。

查看整體目的地狀態

首先,請檢查 request_status 欄位,判斷 Data Manager API 是否已完成 RequestStatusPerDestinationdestination 資料處理作業。

request_status 可能的值如下:

  • PROCESSING:系統仍在處理目的地資料,目前系統不會為目的地填入警告和錯誤

  • SUCCESS:目的地要求處理作業已完成,未發生任何錯誤。檢查處理期間標記的警告

  • FAILURE:所有目的地記錄都因錯誤而失敗。 檢查警告和錯誤,找出所有記錄失敗的原因。此外,也請檢查處理期間標示的警告。

  • PARTIAL_SUCCESS:部分目的地記錄成功,但其他記錄因發生錯誤而失敗。檢查是否有錯誤,找出部分記錄匯入失敗的原因。此外,也請檢查處理期間標記的警告。

依目的地查看事件或目標對象狀態

檢查與擷取要求類型對應的狀態欄位。每個 RequestStatusPerDestination 只能設定下列其中一個欄位:

事件擷取狀態

如果要求是 IngestEventsRequest,系統會填入 events_ingestion_status 欄位。

查看 IngestEventStatusrecord_count,確認收到的記錄總數符合預期。record_count包含成功和失敗的記錄。

目標對象成員的擷取狀態

如果要求是 IngestAudienceMembersRequest,系統就會填入 audience_members_ingestion_status 欄位。以下是每種目標對象資料的IngestAudienceMembersStatus 欄位,可供您檢查。這些欄位只會設定其中一個

user_data_ingestion_status

查看 IngestUserDataStatusrecord_count,確認收到的記錄總數符合預期。record_count 檔案會列出成功和失敗的記錄。

檢查 user_identifier_count,確認收到的使用者 ID 數量符合預期。

如果要求包含足夠的記錄,upload_match_rate_range 會包含要求中記錄的媒合率範圍

mobile_data_ingestion_status

請檢查 record_countIngestMobileDataStatus,確認收到的記錄總數符合預期。record_count 包含成功和失敗的記錄。

檢查 mobile_id_count,確認收到的行動 ID 數量符合預期。

pair_data_ingestion_status

查看 IngestPairDataStatusrecord_count,確認收到的記錄總數符合預期。record_count 檔案會列出成功和失敗的記錄。

檢查 pair_id_count,確認收到的 PAIR ID 數量符合預期。

ppid_data_ingestion_status

查看 IngestPpidDataStatusrecord_count,確認收到的記錄總數符合預期。record_count 檔案會列出成功和失敗的記錄。

檢查 ppid_count,確認收到的 PPID 數量符合預期。

user_id_data_ingestion_status

查看 IngestUserIdDataStatusrecord_count,確認收到的記錄總數符合預期。record_count 檔案會列出成功和失敗的記錄。

檢查 user_id_count,確認收到的使用者 ID 數量符合預期。

目標對象成員移除狀態

如果要求是RemoveAudienceMembersRequest,系統就會填入 audience_members_removal_status 欄位。以下列出各類目標對象資料應檢查的 RemoveAudienceMembersStatus 欄位。這些欄位只會設定其中一個

user_data_removal_status
使用者資料的移除狀態。
mobile_data_removal_status
「行動數據」的移除狀態。
pair_data_removal_status
PAIR 資料的移除狀態。
ppid_data_removal_status
PPID 資料的移除狀態。
user_id_data_removal_status
使用者 ID 資料的移除狀態

查看 record_count,確認收到的記錄總數符合預期。record_count 包含成功和失敗的記錄。

此外,請查看 user_identifier_countmobile_id_countpair_id_count,確認收到的使用者 ID、行動 ID 或 PAIR ID 總數。

檢查警告和錯誤

除了目的地和要求類型的狀態欄位外,RetrieveRequestStatusResponse 也會列出要求的警告和錯誤。

  • 如果出現錯誤,表示 API 完全拒絕記錄。
  • 警告表示 API 並未拒絕記錄,但必須忽略記錄的部分資料。

舉例來說,如果 Google Ads 離線轉換的 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 錯誤,因為有效的 Google Ads 離線轉換 Event 必須至少包含 ad_identifiersuser_data

以下是包含警告和錯誤資訊的回覆欄位。當整體目的地狀態達到 SUCCESSPARTIAL_SUCCESSFAILURE 時,系統就會填入這些欄位。

warning_info

WarningCount 物件的清單。每個 WarningCount 都包含 reason (警告類型) 和 record_count (指出有該類型警告的記錄數)。

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

error_info

ErrorCount 物件的清單。每個 ErrorCount 都包含 reason (錯誤類型) 和 record_count (因該類型錯誤而失敗的記錄數)。