最佳做法和限制

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

提升處理量

• 建議您減少大型工作，而非增加小型工作。

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

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

批次分割作業的完整性

Google Ads API 會將提交的批次工作中的作業分割成較小的子批次進行處理。標準子批次會啟用部分失敗功能，但特定互依作業的子批次會以單一交易的形式，以不可分割的方式處理：

• 連續 AdGroupCriterionOperation 作業 (create、update 和 remove) 針對相同 AdGroup (如果群組中有任何作業失敗，就會失敗並顯示 CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION)。LISTING_GROUPAdGroupCriterion.listing_group
• 連續 AssetGroupListingGroupFilterOperation 作業 (以相同 AssetGroup 為目標的 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 上的 resource_name 或 Campaign) 和其連續子項 create 作業 (AssetGroupAsset 上的 asset_group 或 CampaignAsset) 必須指定相同的負數臨時 ID。campaign
• 請將新 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 最多可支援一百萬項作業。 呼叫 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));
  

單一修改作業大小

雖然整體要求最多可達 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 欄位會指定違反的限制。