Seperti yang dibahas dalam panduan struktur API, setiap resource tingkat teratas di Google Ads API memiliki layanan khusus jenis resource yang sesuai yang mendukung pengubahan instance resource. Anda juga dapat menggunakan
GoogleAdsService.Mutate untuk mengubah
beberapa jenis resource secara atomik dalam satu permintaan.
Panduan ini menggunakan CampaignService untuk
menunjukkan cara mengubah objek Campaign, tetapi konsep yang sama
berlaku untuk semua layanan khusus jenis resource lainnya.
Permintaan modifikasi
Setiap layanan khusus jenis resource memiliki metode mutate yang menerima permintaan modifikasi. Permintaan ini terdiri dari:
customer_id(ataucustomerIddi URL REST)- Koleksi
operations - Setelan eksekusi opsional seperti
partial_failure,validate_only, danresponse_content_type(yang menentukan apakah resource yang dapat diubah atau hanya nama resource yang ditampilkan setelah mutasi)
Misalnya, metode MutateCampaigns dari CampaignService menerima
MutateCampaignsRequest yang terdiri
dari:
customer_id- Koleksi objek
CampaignOperation(operations) - Setelan eksekusi opsional (
partial_failure,validate_only, danresponse_content_typeyang menunjukkan jenis respons yang diinginkan)
Operasi
Objek operasi seperti CampaignOperation memungkinkan Anda menentukan tindakan
yang ingin dilakukan pada satu resource dengan menetapkan kolom operation-nya.
Kolom ini adalah kolom oneof yang terdiri dari atribut berikut:
create- Membuat instance baru resource.
update- Mengupdate resource agar sesuai dengan atribut resource
update. Jika kolom ini ditetapkan, Anda juga harus menetapkanupdate_maskoperasi, yang memberi tahu Google Ads API atribut mana yang harus diubah selama operasi update. Setiap library klien menyertakan utilitas mask kolom atau metode bantuan yang menghasilkanupdate_maskuntuk Anda. remove- Menghapus resource yang ditentukan oleh string nama resource-nya (misalnya,
customers/1234567890/campaigns/987654321).
Karena kolom operation adalah kolom oneof, Anda tidak dapat menggunakan satu operasi untuk mengubah beberapa objek. Misalnya, jika Anda ingin membuat satu
kampanye dan menghapus kampanye lain, tambahkan dua instance CampaignOperation
ke permintaan Anda: satu dengan create yang ditetapkan, dan satu lagi dengan remove yang ditetapkan.
Operasi batch
Meskipun satu operasi hanya dapat membuat, memperbarui, atau menghapus satu resource, satu permintaan modifikasi dapat berisi beberapa operasi. Anda harus menggabungkan operasi ke dalam satu permintaan modifikasi, bukan mengirim beberapa permintaan modifikasi yang masing-masing berisi satu operasi.
Misalnya, jika ingin membuat sepuluh kampanye, Anda harus mengirim satu
MutateCampaignsRequest yang memiliki sepuluh objek CampaignOperation. Untuk mengelompokkan
operasi di berbagai jenis resource ke dalam satu permintaan, gunakan
GoogleAdsService.Mutate atau
resource mutasi.
Mengubah respons
Respons yang ditampilkan bergantung pada apa yang dikirim di kolom response_content_type dari permintaan modifikasi.
Misalnya, jika MUTABLE_RESOURCE ditentukan, respons akan berisi resource_name resource dan kolom yang dapat diubah dari kampanye di campaign. Secara
default (RESOURCE_NAME_ONLY), hanya resource_name yang diisi di setiap
MutateCampaignResult.
Error mutasi
Secara default (partial_failure = false), operasi dalam permintaan modifikasi hanya diterapkan ke akun Google Ads Anda jika setiap operasi dalam permintaan berhasil; jika ada operasi yang gagal, seluruh permintaan akan di-roll back. Untuk permintaan
modifikasi yang mendukung kegagalan parsial (yang memiliki kolom partial_failure pada
pesan permintaan), menetapkan partial_failure = true akan meng-commit operasi yang valid,
sementara operasi yang gagal akan menampilkan error khusus operasi di kolom
partial_failure_error respons. Lihat panduan kegagalan parsial dan panduan error umum untuk mengetahui detail tentang cara menangani error.
Lacak perubahan
Untuk melacak perubahan yang dilakukan pada objek di akun Google Ads, atau untuk mengambil
status objek saat ini, Anda dapat menggunakan resource change_status dan change_event.
change_statusmemberikan ringkasan resource yang telah berubah dalam jangka waktu tertentu.change_eventmemberikan histori perubahan yang mendetail, termasuk nilai lama dan baru dari kolom yang diubah.
Untuk mengkueri resource ini, gunakan metode
GoogleAdsService.SearchStream atau
GoogleAdsService.Search. Baca selengkapnya tentang streaming laporan menggunakan GoogleAdsService.