最佳做法和限制

使用 BatchJobService 時，請注意下列事項。

提升處理量

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

• 依作業類型排序上傳的作業。舉例來說，如果您的工作包含新增廣告活動、廣告群組和廣告群組條件的作業，請在上傳時依序排列作業，先是所有廣告活動作業，接著是所有廣告群組作業，最後是所有廣告群組條件作業。

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

避免並行問題

• 為同一帳戶提交多個並行工作時，請盡量減少工作同時對相同物件執行的可能性，同時維持大型工作大小。許多未完成的工作具有 RUNNING 狀態，嘗試變動同一組物件，可能會導致類似死結的狀況，造成嚴重延遲，甚至工作失敗。

• 請勿在同一個工作中提交多項作業，以免變更同一個物件，因為結果可能無法預測。

以最佳方式擷取結果

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

• 每個網頁最多只能擷取 1,000 個結果。伺服器可能會因負載或其他因素而傳回較少的項目。

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

其他使用指南

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

• 建議您在每個 AddBatchJobOperationsRequest 中新增不超過 1,000 項作業，並使用 sequence_token 將其餘作業上傳至相同工作。視作業內容而定，單一 AddBatchJobOperationsRequest 中的作業過多可能會導致 REQUEST_TOO_LARGE 錯誤。您可以減少作業數量並重試 AddBatchJobOperationsRequest，藉此處理這項錯誤。

限制

• 每個 BatchJob 最多可支援一百萬項作業。

• 每個帳戶最多可同時有 100 個有效或待處理的工作。

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

• 自第 22 版起，每項 AddBatchJobOperations 要求最多只能有 10,000 項變動作業。

• 自第 22 版起，ListBatchJobResultsRequest 中的 page_size 欄位：

  • 如未設定 page_size 或設為 0，則預設值為 1,000 (上限)。
  • 如果 page_size 大於 1,000 或小於 0，API 會傳回 INVALID_PAGE_SIZE 錯誤。

• 每個 AddBatchJobOperationsRequest 大小上限為 10,484,504 個位元組。如果超出此限制，您會收到 INTERNAL_ERROR。您可以在提交要求前判斷要求大小，並在要求過大時採取適當行動。

  Java

  
  static final int MAX_REQUEST_BYTES = 10_484_504;
  
  ... (code to get the request object)
  
  int sizeInBytes = request.getSerializedSize();
  

  Python

  
  from google.ads.googleads.client import GoogleAdsClient
  
  MAX_REQUEST_BYTES = 10484504
  
  ... (code to get the request object)
  
  size_in_bytes = request._pb.ByteSize()
  

  Ruby

  
  require 'google/ads/google_ads'
  
  MAX_REQUEST_BYTES = 10484504
  
  ... (code to get the request object)
  
  size_in_bytes = request.to_proto.bytesize
  

  PHP

  
  use Google\Ads\GoogleAds\V16\Resources\Campaign;
  
  const MAX_REQUEST_BYTES = 10484504;
  
  ... (code to get the request object)
  
  $size_in_bytes = $campaign->byteSize() . PHP_EOL;
  

  .NET

  
  using Google.Protobuf;
  const int MAX_REQUEST_BYTES = 10484504;
  
  ... (code to get the request object)
  
  int sizeInBytes = request.ToByteArray().Length;
  

  Perl

  
  use Devel::Size qw(total_size);
  use constant MAX_REQUEST_BYTES => 10484504;
  
  ... (code to get the request object)
  
  my $size_in_bytes = total_size($request);