Menggunakan filter kelompok listing dalam tugas batch

Saat Anda menggunakan filter kelompok listing dalam konteks AdGroupCriterion.listing_group atau AssetGroupListingGroupFilter, perhatikan pertimbangan 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 listingan 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 listingan diperlakukan secara atomik.

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

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

Pertimbangkan cara pengelompokan operasi:

• Semua operasi AssetGroupListingGroupFilterOperation berturut-turut (create, update, dan remove) yang menargetkan AssetGroup yang sama dikelompokkan bersama dalam sub-batch atomik (tidak ada perilaku kegagalan parsial).
• Semua operasi AdGroupCriterionOperation berturut-turut (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 parsial).

Catatan: Jika Anda juga membuat AssetGroup dalam tugas batch yang sama, tempatkan operasi AssetOperation (create) prasyarat untuk resource Asset baru sebelum AssetGroupOperation (create), yang langsung diikuti dengan operasi AssetGroupAssetOperation (create) (yang dijalankan bersama dalam sub-batch atomik sebelumnya), lalu operasi AssetGroupListingGroupFilterOperation berturut-turut (yang dijalankan di sub-batch atomik berikutnya). Karena keduanya membentuk dua sub-batch terpisah, kegagalan dalam sub-batch AssetGroupListingGroupFilterOperation akan me-roll back filter kelompok listing tanpa me-roll back resource 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 disisipkan 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 seperti yang dikirim menggunakan Google Ads API. Dalam kotak abu-abu, setiap operasi dikelompokkan berdasarkan warna untuk mewakili sub-batch yang dibuat oleh server Google Ads API. Urutan operasi di setiap kotak abu-abu sesuai dengan urutan penambahan operasi ke tugas batch.

Batasan

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

• Satu sub-batch atomik dari operasi AdGroupCriterionOperation berturut-turut (create, update, dan remove) untuk kriteria LISTING_GROUP (AdGroupCriterion.listing_group) yang menargetkan AdGroup yang sama tidak boleh melebihi 20.000 operasi. Namun, sebaiknya jangan 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 berturut-turut (create, update, dan remove) yang menargetkan AssetGroup yang sama tidak boleh melebihi 10.000 operasi.
• Melanggar salah satu batas jumlah operasi ini (atau melebihi batas ukuran byte serial internal server untuk satu sub-batch) akan membatalkan tugas batch pada sub-batch tersebut: sub-batch sebelumnya yang sudah selesai tetap di-commit, sedangkan semua operasi dalam sub-batch yang melanggar dan sub-batch berikutnya akan gagal dengan InternalError.INTERNAL_ERROR.

Pemecahan masalah

Operasi filter kelompok listing dalam tugas batch diproses sebagai satu transaksi, yang dapat menyebabkan skenario saat banyak operasi gagal karena sejumlah kecil operasi yang salah. Selain itu, karena cara operasi BatchJob diproses, akar masalah kegagalan mungkin muncul pada indeks sebelum atau setelah kegagalan downstream.

Misalnya, saat memproses respons dari ListBatchJobResults:

• Untuk kelompok listing AdGroupCriterionOperation, Anda mungkin mendapati bahwa operasi berturut-turut yang menarget 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 berturut-turut 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 akar masalah, lakukan iterasi melalui pesan status di setiap BatchJobResult—sebelum dan sesudah operation_index error transaksi—untuk operasi yang memiliki ID AdGroup atau AssetGroup yang sama.