Menggunakan filter kelompok listing dalam tugas batch

Saat Anda menggunakan filter kelompok listingan dalam konteks AdGroupCriterion.listing_group atau AssetGroupListingGroupFilter, pertimbangkan hal-hal berikut saat mendesain integrasi Anda.

Pemisahan batch

Poin Penting: Sebaiknya tambahkan operasi AssetGroupListingGroupFilterOperation (create, update, dan remove) yang menargetkan AssetGroup yang sama, dan operasi AdGroupCriterionOperation (create, update, dan remove) untuk kriteria LISTING_GROUP (AdGroupCriterion.listing_group) yang menargetkan AdGroup yang sama, ke tugas batch secara berurutan, sehingga kumpulan operasi diperlakukan secara atomik selama pemisahan batch.

Jika ada operasi dalam tugas batch yang berisi kriteria grup iklan atau filter kelompok listing grup aset, operasi dalam tugas batch akan dibagi menjadi beberapa sub-batch saat diterima oleh server Google Ads API. Tidak seperti operasi standar dalam tugas batch, setiap sub-batch yang berisi operasi filter kelompok listing diperlakukan secara atomik.

Cara tugas batch yang berisi filter kelompok listingan dibagi menjadi sub-batch ditentukan oleh faktor berikut:

1. Jenis filter kelompok listing
2. AdGroup atau AssetGroup kelompok listingan yang ditargetkan oleh filter
3. Urutan operasi

Pertimbangkan cara pengelompokan operasi:

• Semua operasi AssetGroupListingGroupFilterOperation berurutan (create, update, dan remove) yang menargetkan AssetGroup yang sama dikelompokkan bersama dalam sub-batch atomik (tidak ada perilaku kegagalan sebagian).
• Semua operasi AdGroupCriterionOperation berurutan (create, update, dan remove) untuk kriteria LISTING_GROUP (AdGroupCriterion.listing_group) yang menargetkan AdGroup yang sama dikelompokkan bersama dalam sub-batch atomik (tidak ada perilaku kegagalan parsial).
• Semua operasi berurutan lainnya dikelompokkan bersama dalam sub-batch non-atomik (perilaku kegagalan sebagian).

Catatan: Jika Anda juga membuat AssetGroup dalam batch yang sama, tempatkan operasi prasyarat AssetOperation (create) untuk resource Asset baru sebelum AssetGroupOperation (create), diikuti langsung dengan operasi AssetGroupAssetOperation (create) (yang dijalankan bersama dalam sub-batch atomik sebelumnya), lalu operasi AssetGroupListingGroupFilterOperation berurutan (yang dijalankan dalam sub-batch atomik berikutnya). Karena membentuk dua sub-batch terpisah, kegagalan dalam sub-batch AssetGroupListingGroupFilterOperation akan membatalkan filter grup listingan tanpa membatalkan AssetGroup dan AssetGroupAsset yang baru dibuat.

Istilah Utama: Berurutan mengacu pada urutan operasi dalam tugas batch. Jika operasi yang menargetkan AdGroup atau AssetGroup yang sama diselingi dengan operasi yang menargetkan grup yang berbeda, operasi tersebut akan dibagi menjadi sub-batch terpisah dan tidak lagi diproses sebagai satu transaksi atomik.

Diagram berikut menggambarkan konsep tersebut. Setiap kotak abu-abu mewakili tugas batch yang dikirimkan menggunakan Google Ads API. Dalam kotak abu-abu, setiap operasi dikelompokkan berdasarkan warna untuk merepresentasikan sub-batch yang dibuat oleh server Google Ads API. Urutan operasi di setiap kotak abu-abu sesuai dengan urutan operasi yang akan ditambahkan ke tugas batch.

Batasan

Saat menggunakan filter kelompok listingan dalam konteks tugas batch, batasan berikut berlaku:

• Satu sub-batch atomik dari operasi AdGroupCriterionOperation berurutan (create, update, dan remove) untuk kriteria LISTING_GROUP (AdGroupCriterion.listing_group) yang menargetkan AdGroup yang sama tidak boleh melebihi 20.000 operasi. Namun, sebaiknya tidak melebihi 10.000 operasi. Karena setiap AddBatchJobOperationsRequest dibatasi hingga 10.000 operasi, sub-batch AdGroup yang berisi 10.001 hingga 20.000 operasi harus diupload di setidaknya dua permintaan AddBatchJobOperations berturut-turut.
• Satu sub-batch atomik dari operasi AssetGroupListingGroupFilterOperation berurutan (create, update, dan remove) yang menargetkan AssetGroup yang sama tidak boleh melebihi 10.000 operasi.
• Melanggar salah satu batas jumlah operasi ini (atau melampaui batas ukuran byte berseri internal server untuk satu sub-batch) akan membatalkan tugas batch pada sub-batch tersebut: semua sub-batch sebelumnya yang telah selesai akan tetap di-commit, sementara semua operasi dalam sub-batch yang melanggar dan sub-batch berikutnya akan gagal dengan InternalError.INTERNAL_ERROR.

Pemecahan masalah

Operasi filter kelompok listingan dalam tugas batch diproses sebagai satu transaksi, yang dapat menyebabkan banyak operasi gagal karena sejumlah kecil operasi yang salah. Selain itu, karena cara pemrosesan operasi BatchJob, akar penyebab kegagalan mungkin muncul pada indeks sebelum atau setelah kegagalan hilir.

Misalnya, saat memproses respons dari ListBatchJobResults:

• Untuk grup listingan AdGroupCriterionOperation, Anda mungkin mendapati bahwa operasi berurutan yang menargetkan AdGroup yang sama gagal dengan CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION (Product group operations are atomic within the same ad group. This operation failed because another operation targeting the same ad group ID was invalid.).
• Untuk operasi AssetGroupListingGroupFilterOperation, Anda mungkin mendapati bahwa operasi berurutan yang menargetkan AssetGroup yang sama gagal dengan BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE.

Error ini menunjukkan bahwa operasi pada indeks tersebut di-roll back karena operasi lain dalam sub-batch atomik yang sama gagal. Untuk mengidentifikasi penyebab utama masalah, lakukan iterasi pada pesan status di setiap BatchJobResult—sebelum dan setelah operation_index error transaksi—untuk operasi yang berbagi ID AdGroup atau AssetGroup yang sama.