Mengubah objek

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 (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
  • Koleksi objek CampaignOperation (operations)
  • Setelan eksekusi opsional (partial_failure, validate_only, dan response_content_type yang 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 menetapkan update_mask operasi, 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 menghasilkan 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 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_status memberikan ringkasan resource yang telah berubah dalam jangka waktu tertentu.
  • change_event memberikan 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.