Mengubah objek

Seperti yang dibahas dalam panduan struktur API, setiap resource tingkat teratas di Google Ads API memiliki layanan khusus jenis resource yang mendukung modifikasi instance resource. Anda juga dapat menggunakan GoogleAdsService.Mutate untuk mengubah beberapa jenis resource secara atomik dalam satu permintaan.

Panduan ini menggunakan CampaignService untuk mendemonstrasikan modifikasi objek Campaign, tetapi konsep yang sama berlaku untuk semua layanan khusus jenis resource lainnya.

Permintaan perubahan

Setiap layanan khusus jenis resource memiliki metode mutate yang menerima permintaan mutate. Permintaan ini terdiri dari:

• customer_id (atau customerId di URL REST)
• Koleksi operations
• Setelan eksekusi opsional seperti partial_failure, validate_only, dan response_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
• Kumpulan objek CampaignOperation (operations)
• Setelan eksekusi opsional (partial_failure, validate_only, dan response_content_type yang menunjukkan jenis respons pilihan)

Operasi

Objek operasi seperti CampaignOperation memungkinkan Anda menentukan tindakan yang ingin Anda lakukan pada satu resource dengan menetapkan kolom operation-nya. Kolom ini adalah kolom oneof yang terdiri dari atribut berikut:

create

Membuat instance resource baru.

update

Memperbarui resource agar sesuai dengan atribut resource update. Jika kolom ini ditetapkan, Anda juga harus menetapkan update_mask operasi, yang memberi tahu Google Ads API atribut mana yang akan diubah selama operasi pembaruan. Setiap library klien menyertakan utilitas atau metode helper mask kolom yang membuat update_mask untuk 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 Anda ingin membuat sepuluh kampanye, Anda harus mengirimkan satu MutateCampaignsRequest yang memiliki sepuluh objek CampaignOperation. Untuk mengelompokkan operasi di berbagai jenis resource ke dalam satu permintaan, gunakan GoogleAdsService.Mutate atau resource yang mengubah.

Respons mutasi

Yang ditampilkan dalam respons bergantung pada apa yang dikirim di kolom response_content_type permintaan modifikasi. Misalnya, jika MUTABLE_RESOURCE ditentukan, maka respons berisi resource_name resource dan kolom kampanye yang dapat diubah dalam campaign. Secara default (RESOURCE_NAME_ONLY), hanya resource_name yang diisi di setiap MutateCampaignResult.

Error perubahan

Secara default (partial_failure = false), operasi dalam permintaan modifikasi diterapkan ke akun Google Ads Anda hanya jika setiap operasi dalam permintaan berhasil; jika ada operasi yang gagal, seluruh permintaan akan di-roll back. Untuk permintaan perubahan yang mendukung kegagalan sebagian (yang memiliki kolom partial_failure pada pesan permintaan), menyetel partial_failure = true akan melakukan operasi yang valid, sementara operasi yang gagal akan menampilkan error khusus operasi di kolom partial_failure_error respons. Lihat panduan kegagalan sebagiandan panduan kesalahan umumuntuk mengetahui detail tentang penanganan error.

Melacak perubahan

Untuk melacak perubahan yang dilakukan pada objek di akun Google Ads Anda, atau untuk mengambil status objek saat ini, Anda dapat menggunakan resource change_status dan change_event.

• change_status memberikan ringkasan sumber daya yang telah berubah dalam jangka waktu tertentu.
• change_event memberikan histori mendetail tentang perubahan, termasuk nilai lama dan baru dari kolom yang diubah.

Untuk membuat kueri resource ini, gunakan metode GoogleAdsService.SearchStream atau GoogleAdsService.Search. Baca selengkapnya tentang streaming laporan menggunakan GoogleAdsService.