Praktik terbaik dan batasan

Pertimbangkan panduan berikut saat menggunakan BatchJobService.

Meningkatkan throughput

• Lebih sedikit tugas yang lebih besar lebih disukai daripada banyak tugas yang lebih kecil.

• Urutkan operasi yang diupload menurut jenis operasi (kecuali untuk operasi yang saling bergantung yang harus dikelompokkan secara berurutan dalam sub-batch atomik). Misalnya, jika tugas Anda berisi operasi untuk menambahkan kampanye standar, grup iklan, dan kriteria grup iklan, urutkan operasi dalam upload Anda sehingga semua operasi kampanye dilakukan terlebih dahulu, diikuti dengan semua operasi grup iklan, dan terakhir semua operasi kriteria grup iklan.

• Dalam operasi dengan jenis yang sama, pengelompokan menurut resource induk dapat meningkatkan performa. Misalnya, jika Anda memiliki serangkaian objek AdGroupCriterionOperation, akan lebih efisien untuk mengelompokkan operasi menurut grup iklan daripada mencampuradukkan operasi yang memengaruhi kriteria grup iklan di grup iklan yang berbeda.

Atomisitas dalam pemisahan batch

Google Ads API membagi operasi dalam tugas batch yang dikirimkan menjadi sub-batch yang lebih kecil untuk diproses. Meskipun sub-batch standar dijalankan dengan mengaktifkan kegagalan parsial, sub-batch untuk operasi yang saling bergantung tertentu diproses secara atomik sebagai satu transaksi:

• Operasi AdGroupCriterionOperation berurutan (create, update, dan remove) untuk kriteria LISTING_GROUP (AdGroupCriterion.listing_group) yang menargetkan AdGroup yang sama (gagal dengan CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION jika ada operasi dalam grup yang gagal).
• Operasi AssetGroupListingGroupFilterOperation berurutan (create, update, dan remove) yang menargetkan AssetGroup yang sama (gagal dengan BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE jika ada operasi dalam grup yang gagal).
• AssetGroupOperation (create) yang segera diikuti oleh hingga 999 operasi AssetGroupAssetOperation (create) yang menargetkan AssetGroup yang sama (gagal dengan BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE jika ada operasi dalam grup yang gagal). Setiap AssetGroupOperation (update atau remove) dieksekusi dalam sub-batch operasi tunggal mandirinya sendiri.
• CampaignOperation Performa Maksimal (create) dengan Panduan Merek diaktifkan (brand_guidelines_enabled ditetapkan ke true atau tidak ditetapkan, karena secara default true kecuali jika ditetapkan secara eksplisit ke false atau membuat kampanye Performa Maksimal untuk sasaran perjalanan) segera diikuti oleh hingga 999 operasi CampaignAssetOperation (create) yang menargetkan Campaign yang sama (gagal dengan BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE jika ada operasi dalam grup yang gagal). Kampanye Performa Maksimal Retail (dengan feed Merchant Center) dapat dibuat tanpa menautkan aset merek CampaignAsset dalam sub-batch atomik yang sama.

Untuk sub-batch pembuatan AssetGroup dan Performa Maksimal Campaign (hingga total 1.000 operasi per sub-batch; operasi create turunan di luar 999 akan masuk ke sub-batch non-atomik berikutnya):

• Operasi create induk (resource_name di AssetGroup atau Campaign) dan operasi create anak berikutnya (asset_group di AssetGroupAsset atau campaign di CampaignAsset) harus menentukan ID sementara negatif yang sama.
• Tempatkan operasi prasyarat AssetOperation (create) untuk resource Asset baru sebelum induk AssetGroupOperation atau CampaignOperation (create), jangan pernah di antara induk create dan operasi penautan turunannya create (yang akan segera menutup sub-batch atomik dan memisahkan pembuatan resource induk dari aset tertautnya).

Jika sub-batch atomik gagal, BatchJobResult.status operasi yang bermasalah akan berisi error validasi pokok, sementara operasi yang tersisa dalam sub-batch tersebut akan di-roll back dengan error transaksi yang sesuai untuk sub-batch tersebut. Periksa entri BatchJobResult yang berdekatan yang memiliki ID AdGroup, AssetGroup, atau Campaign yang sama untuk mengidentifikasi error penyebab utama.

Jika operasi terkait dalam salah satu grup ini tidak ditambahkan secara berurutan, Google Ads API akan membagi operasi tersebut ke dalam sub-batch terpisah, sehingga menyebabkan modifikasi gagal memenuhi persyaratan aset minimum atau membuat hierarki kelompok listingan tidak lengkap. Lihat Menggunakan filter grup listingan dalam tugas batch dan Pemrosesan batch Performa Maksimal untuk mengetahui detailnya.

Pengelompokan logis

Saat mengubah hierarki penargetan produk (AssetGroupListingGroupFilterOperation di kampanye Performa Maksimal atau AdGroupCriterionOperation di kampanye Shopping) atau membuat AssetGroup atau Performa Maksimal Campaign baru, kelompokkan semua operasi yang menargetkan sumber daya induk yang sama (AssetGroup, AdGroup, atau Campaign) secara berurutan. Hal ini mengurangi pertentangan penguncian backend dan mempertahankan pohon yang saling bergantung.

Konsistensi data

Karena pohon filter grup listingan dan persyaratan aset Performa Maksimal divalidasi di akhir setiap transaksi sub-batch atomik, hindari membagi pembaruan ke resource induk yang sama di seluruh rentang yang tidak berkesinambungan dalam tugas atau di seluruh tugas serentak.

Menghindari masalah konkurensi

• Saat mengirimkan beberapa tugas serentak untuk akun yang sama, kurangi kemungkinan tugas beroperasi pada objek yang sama pada saat yang sama sambil mempertahankan ukuran tugas yang besar. Banyak tugas yang belum selesai dengan status RUNNING yang mencoba mengubah kumpulan objek yang sama dapat menyebabkan kondisi seperti kebuntuan, sehingga menyebabkan perlambatan parah dan bahkan kegagalan tugas.

• Jangan mengirimkan beberapa operasi yang mengubah objek yang sama dalam tugas yang sama, karena hasilnya tidak dapat diprediksi.

Mengambil hasil secara optimal

• Jangan terlalu sering melakukan polling status tugas atau Anda berisiko mengalami error pembatasan kapasitas.

• Biarkan page_size tidak disetel (atau setel ke maksimum 1000) saat memanggil ListBatchJobResults untuk meminimalkan perjalanan pulang pergi penomoran halaman, dan hanya setel response_content_type ke MUTABLE_RESOURCE jika aplikasi Anda memeriksa kolom resource yang ditampilkan di luar resource_name.

• Urutan hasil sama dengan urutan upload.

Panduan penggunaan tambahan

• Anda dapat menetapkan batas atas durasi tugas batch diizinkan berjalan sebelum dibatalkan. Saat membuat tugas batch baru, tetapkan kolom metadata.execution_limit_seconds ke batas waktu yang Anda inginkan, dalam detik. Tidak ada batas waktu default jika metadata.execution_limit_seconds tidak ditetapkan.

• Meskipun batas protokolnya adalah 10.000 operasi per permintaan, sebaiknya tambahkan tidak lebih dari 1.000 operasi per AddBatchJobOperationsRequest dan gunakan sequence_token untuk mengupload operasi lainnya ke tugas yang sama. Bergantung pada ukuran operasi, mengirim terlalu banyak operasi dalam satu AddBatchJobOperationsRequest dapat menyebabkan error BatchJobError.REQUEST_TOO_LARGE. Anda dapat mengatasi error ini dengan mengurangi jumlah operasi dan mencoba lagi AddBatchJobOperationsRequest.

Batasan

• Setiap BatchJob mendukung hingga satu juta operasi. Jika batas ini terlampaui saat memanggil AddBatchJobOperations, error ResourceCountLimitExceededError.RESOURCE_LIMIT akan muncul (dengan ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB di ErrorDetails.resource_count_details).

• Setiap akun dapat memiliki hingga 100 tugas aktif atau tertunda secara bersamaan. Jika batas ini terlampaui saat membuat tugas batch dengan MutateBatchJob, error ResourceCountLimitExceededError.RESOURCE_LIMIT akan muncul (dengan ResourceLimitType.BATCH_JOBS_PER_CUSTOMER di ErrorDetails.resource_count_details).

• Pekerjaan tertunda yang sudah lebih dari 7 hari akan otomatis dihapus.

• Setiap AddBatchJobOperationsRequest memiliki batas keras 10.000 operasi perubahan per permintaan. Melebihi 10.000 operasi dalam satu permintaan akan menampilkan error BatchJobError.REQUEST_TOO_LARGE.

• Untuk kolom page_size di ListBatchJobResultsRequest:

  • Jika page_size tidak ditetapkan atau 0, nilai defaultnya adalah maksimum 1000.
  • Jika page_size melebihi 1000, atau kurang dari 0, API akan menampilkan error BatchJobError.INVALID_PAGE_SIZE.

• Setiap AddBatchJobOperationsRequest memiliki ukuran maksimum 41.937.920 byte. Jika Anda melampaui batas ini, Anda akan menerima error BatchJobError.REQUEST_TOO_LARGE (atau INTERNAL_ERROR jika ditolak di lapisan transport). Anda dapat menentukan ukuran permintaan yang diserialisasi sebelum mengirimkan dan melakukan tindakan yang sesuai jika terlalu besar:

  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()
  

  Ruby

  
  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));
  

Ukuran operasi mutasi tunggal

Meskipun keseluruhan permintaan dapat mencapai 41.937.920 byte, ukuran yang diserialisasi dari satu MutateOperation dalam batch dibatasi hingga 10.484.504 byte (10 MiB dikurangi 1.256 byte). Jika batas ini terlampaui, error BatchJobError.REQUEST_TOO_LARGE akan muncul. Perhatikan bahwa meskipun dokumentasi referensi untuk BatchJobError.REQUEST_TOO_LARGE mengutip nilai minimum 10.484.504 byte, AddBatchJobOperations menampilkan kode error yang sama ini jika salah satu dari tiga nilai minimum permintaan (41.937.920 byte total permintaan, 10.484.504 byte operasi tunggal, atau 10.000 operasi per panggilan) terlampaui, dengan kolom message error yang menentukan batas yang dilanggar.