Praktik terbaik dan batasan

Pertimbangkan panduan ini saat menggunakan BatchJobService.

Meningkatkan throughput

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

  • Urutkan operasi yang diupload berdasarkan 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 berada di urutan pertama, diikuti dengan semua operasi grup iklan, dan terakhir semua operasi kriteria grup iklan.

  • Dalam operasi dengan jenis yang sama, performa dapat ditingkatkan dengan mengelompokkannya berdasarkan resource induk. Misalnya, jika Anda memiliki serangkaian objek AdGroupCriterionOperation, akan lebih efisien untuk mengelompokkan operasi berdasarkan grup iklan daripada mencampur operasi yang memengaruhi kriteria grup iklan di berbagai grup iklan.

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 kegagalan parsial diaktifkan, sub-batch untuk operasi tertentu yang saling bergantung diproses secara atomik sebagai satu transaksi:

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

Jika sub-batch atomik gagal, BatchJobResult.status operasi yang bermasalah akan berisi error validasi yang mendasarinya, sedangkan 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 di salah satu grup ini tidak ditambahkan secara berurutan, Google Ads API akan membaginya ke dalam sub-batch terpisah, sehingga menyebabkan modifikasi gagal memenuhi persyaratan aset minimum atau membuat hierarki kelompok listing tidak lengkap. Lihat Menggunakan filter kelompok listing 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 Campaign Performa Maksimal baru, kelompokkan semua operasi yang menargetkan resource induk yang sama (AssetGroup, AdGroup, atau Campaign) secara berurutan. Hal ini mengurangi pertentangan kunci backend dan menjaga pohon yang saling bergantung tetap bersama.

Konsistensi data

Karena hierarki filter kelompok listingan dan persyaratan aset Performa Maksimal divalidasi di akhir setiap transaksi sub-batch atomik, hindari memisahkan pembaruan ke resource induk yang sama di seluruh rentang yang tidak berkelanjutan 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 secara bersamaan 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 deadlock, sehingga mengakibatkan perlambatan yang 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 ditetapkan (atau tetapkan ke maksimum 1000) saat memanggil ListBatchJobResults untuk meminimalkan round trip penomoran halaman, dan hanya tetapkan 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 yang diizinkan untuk 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 protokol 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 menangani error ini dengan mengurangi jumlah operasi dan mencoba ulang 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).

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

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

  • Untuk kolom page_size di ListBatchJobResultsRequest:

  • Setiap AddBatchJobOperationsRequest memiliki ukuran maksimum 41.937.920 byte. Jika melebihi batas ini, Anda akan menerima error BatchJobError.REQUEST_TOO_LARGE (atau INTERNAL_ERROR jika ditolak di lapisan transpor). Anda dapat menentukan ukuran permintaan yang diserialisasi sebelum mengirimkannya dan mengambil tindakan yang sesuai jika ukurannya 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 serial 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 saat salah satu dari tiga nilai minimum permintaan (total byte permintaan 41.937.920, byte operasi tunggal 10.484.504, atau 10.000 operasi per panggilan) terlampaui, dengan kolom message error yang menentukan batas yang dilanggar.

Sebelumnya
Filter kelompok listingan