最佳做法和限制

使用 BatchJobService 時，請參考下列準則。

提高處理量

• 建議您執行少量的大型工作，而非大量的小型工作。

• 按照作業類型排序上傳的作業 (但相互依賴的作業必須連續分組在不可分割的子批次中)。舉例來說，如果您的工作包含新增標準廣告活動、廣告群組和廣告群組條件的操作，請在上傳時排序操作，讓所有廣告活動操作排在最前面，接著是所有廣告群組操作，最後是所有廣告群組條件操作。

• 在相同類型的作業中，依據父項資源分組可以提升效能。舉例來說，如果您有一系列 AdGroupCriterionOperation 物件，建議您依廣告群組將作業分組，而不是混合會影響不同廣告群組中廣告群組條件的作業，這樣會更有效率。

批次分割的完整性

Google Ads API 會將提交的批次工作拆分為較小的子批次，標準子批次會在啟用部分失敗的情況下執行，而某些相互依賴作業的子批次則會以單一交易的形式進行原子處理：

• 針對相同 AdGroup 的 LISTING_GROUP 條件 (AdGroupCriterion.listing_group) 執行連續 AdGroupCriterionOperation 作業 (create、update 和 remove) (如果群組中的任何作業失敗，則會失敗並傳回 CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION)。
• 針對相同 AssetGroup 的連續 AssetGroupListingGroupFilterOperation 作業 (create、update 和 remove) (如果群組中的任何作業失敗，則會失敗並顯示 BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE)。
• AssetGroupOperation (create) 後面緊接著最多 999 個 AssetGroupAssetOperation (create) 作業，指定相同的 AssetGroup (如果群組中的任何作業失敗，則會失敗並顯示 BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE)。每個 AssetGroupOperation (update 或 remove) 都會在獨立的單一作業子批次中執行。
• 最高成效廣告活動 CampaignOperation (create) 啟用品牌宣傳指南 (brand_guidelines_enabled 設為 true 或未設定，因為除非明確設為 false 或建立旅遊目標專用的最高成效廣告活動，否則預設為 true)，緊接著最多 999 個 CampaignAssetOperation (create) 作業，指定相同的 Campaign (如果群組中的任何作業失敗，則會失敗並顯示 BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE)。建立零售最高成效廣告活動 (含 Merchant Center 動態饋給) 時，不一定要在同一個原子子批次中連結品牌 CampaignAsset 資源。

AssetGroup 和最高成效廣告活動 Campaign 建立子批次 (每個子批次最多 1,000 項作業；超過 999 項的子 create 作業會移至下一個非不可分割子批次)：

• 父項 create 作業 (AssetGroup 或 Campaign 上的 resource_name) 及其連續子項 create 作業 (AssetGroupAsset 上的 asset_group 或 CampaignAsset 上的 campaign) 必須指定相同的負臨時 ID。
• 請將新 Asset 資源的任何必要 AssetOperation (create) 作業，放在父項 AssetGroupOperation 或 CampaignOperation (create)「之前」，切勿放在父項 create 和其子連結 create 作業之間 (這會立即關閉原子子批次，並將父項資源建立作業與其連結資產分開)。

如果不可分割的子批次失敗，違規作業的 BatchJobResult.status 會包含基礎驗證錯誤，而該子批次中的其餘作業則會復原，並顯示該子批次的對應交易錯誤。檢查共用相同 AdGroup、AssetGroup 或 Campaign ID 的相鄰 BatchJobResult 項目，找出根本原因。

如果未連續新增這些群組中的相關作業，Google Ads API 會將這些作業拆分到不同的子批次，導致修改作業不符合最低素材資源規定，或商家資訊群組樹狀結構不完整。詳情請參閱「在批次工作中套用商家資訊群組篩選器」和「最高成效廣告活動批次處理」。

邏輯群組

修改產品指定階層 (最高成效廣告活動中的 AssetGroupListingGroupFilterOperation 或購物廣告活動中的 AdGroupCriterionOperation)，或建立新的 AssetGroup 或最高成效 Campaign 時，請將指定相同父項資源 (AssetGroup、AdGroup 或 Campaign) 的所有作業連續分組。這可減少後端鎖定爭用，並將相互依賴的樹狀結構保持在一起。

資料一致性

由於系統會在每個原子子批次交易結束時，驗證商家資訊群組篩選器樹狀結構和最高成效廣告活動素材資源規定，因此請避免在工作的不連續範圍內，或在並行工作中，分割對相同父項資源的更新。

避免並行問題

• 為同一個帳戶提交多項並行工作時，請降低工作同時在相同物件上執行的可能性，同時維持大型工作。如果有多項未完成的工作狀態為 RUNNING，且嘗試變更同一組物件，可能會導致類似死結的情況，造成嚴重速度減慢，甚至工作失敗。

• 請勿在同一工作中提交多項會變更相同物件的操作，否則可能導致無法預測的結果。

以最佳方式擷取結果

• 請勿過於頻繁地輪詢工作狀態，否則可能會發生頻率限制錯誤。

• 呼叫 ListBatchJobResults 時，請將 page_size 保持未設定狀態 (或設為最大值 1000)，盡可能減少分頁來回次數。只有在應用程式檢查傳回的資源欄位超過 resource_name 時，才將 response_content_type 設為 MUTABLE_RESOURCE。

• 結果順序與上傳順序相同。

其他使用指南

• 您可以設定批次工作的執行時間上限，超過這個上限就會取消工作。建立新的批次工作時，請將 metadata.execution_limit_seconds 欄位設為偏好的時間限制 (以秒為單位)。如未設定 metadata.execution_limit_seconds，則沒有預設時間限制。

• 雖然通訊協定限制每項要求最多 10,000 項作業，但建議您在每個 AddBatchJobOperationsRequest 中新增不超過 1,000 項作業，並使用 sequence_token 將其餘作業上傳至同一工作。視作業大小而定，在單一 AddBatchJobOperationsRequest 中傳送過多作業可能會導致 BatchJobError.REQUEST_TOO_LARGE 錯誤。如要處理這項錯誤，請減少作業數量，然後重試 AddBatchJobOperationsRequest。

限制

• 每個 BatchJob 最多支援 100 萬項作業。呼叫 AddBatchJobOperations 時，如果超出這項限制，系統會傳回 ResourceCountLimitExceededError.RESOURCE_LIMIT 錯誤 (ErrorDetails.resource_count_details 中包含 ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB)。

• 每個帳戶最多可同時有 100 項進行中或待處理的工作。 使用 MutateBatchJob 建立批次工作時，如果超出這項限制，系統會傳回 ResourceCountLimitExceededError.RESOURCE_LIMIT 錯誤 (ErrorDetails.resource_count_details 中包含 ResourceLimitType.BATCH_JOBS_PER_CUSTOMER)。

• 系統會自動移除超過 7 天的待處理工作。

• 每個 AddBatchJobOperationsRequest 的硬性限制為每次要求最多 10,000 次變動操作。如果單一要求超過 10,000 項作業，系統會傳回 BatchJobError.REQUEST_TOO_LARGE 錯誤。

• ListBatchJobResultsRequest 中的 page_size 欄位：

  • 如果未設定 page_size 或設為 0，則預設為最大值 1000。
  • 如果 page_size 超過 1000 或小於 0，API 會傳回 BatchJobError.INVALID_PAGE_SIZE 錯誤。

• 每個 AddBatchJobOperationsRequest 的大小上限為 41,937,920 位元組。如果超出這項限制，系統會傳回 BatchJobError.REQUEST_TOO_LARGE 錯誤 (如果是在傳輸層遭到拒絕，則會傳回 INTERNAL_ERROR)。您可以在提交前判斷要求的序列化大小，並在要求過大時採取適當行動：

  Java

  
  static final int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.getSerializedSize();
  

  C#

  
  const int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.CalculateSize();
  

  PHP

  
  const MAX_REQUEST_BYTES = 41937920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  $size_in_bytes = $request->byteSize();
  

  Python

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  size_in_bytes = type(request).pb(request).ByteSize()
  

  小茹

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  size_in_bytes = request.to_proto.bytesize
  

  Perl

  
  use JSON::XS;
  use constant MAX_REQUEST_BYTES => 41937920;
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  # The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
  # conservative upper-bound estimate of the serialized request size.
  my $json_encoder = JSON::XS->new->utf8->convert_blessed;
  my $size_in_bytes = length($json_encoder->encode($request));
  

單一 mutate 作業大小

雖然整體要求最多可達 41,937,920 個位元組，但批次中單一 MutateOperation 的序列化大小上限為 10,484,504 個位元組 (10 MiB 減去 1,256 個位元組)。如果超過這項限制，系統會傳回 BatchJobError.REQUEST_TOO_LARGE 錯誤。請注意，雖然 BatchJobError.REQUEST_TOO_LARGE 的參考文件引用了 10,484,504 位元組的門檻，但只要超過三個要求門檻 (總要求位元組數 41,937,920、單一作業位元組數 10,484,504，或每次呼叫 10,000 次作業) 的任一項，AddBatchJobOperations 就會傳回相同的錯誤代碼，並在錯誤的 message 欄位中指定違反的限制。