Struktur API

Panduan ini memperkenalkan komponen utama yang membentuk Google Ads API. Google Ads API terdiri dari resource dan layanan. Resource merepresentasikan entitas Google Ads, sementara layanan mengambil dan memanipulasi entitas Google Ads.

Hierarki objek

Akun Google Ads dapat dilihat sebagai hierarki objek.

• Resource tingkat teratas akun adalah customer.

• Setiap pelanggan berisi satu atau beberapa kampanye yang aktif.

• Setiap kampanye berisi satu atau beberapa grup iklan, yang digunakan untuk mengelompokkan iklan Anda ke dalam kumpulan yang logis.

• Iklan grup iklan mewakili iklan yang Anda jalankan di grup iklan. Kecuali untuk kampanye Aplikasi, yang hanya dapat memiliki satu iklan grup iklan per grup iklan, setiap grup iklan berisi satu atau beberapa iklan grup iklan.

Kampanye Performa Maksimal menggunakan struktur yang berbeda dari jenis kampanye lainnya: bukan grup iklan dan iklan grup iklan, kampanye Performa Maksimal berisi grup aset. Anda menautkan aset materi iklan ke grup aset menggunakan AssetGroupAsset dan melampirkan sinyal audiens atau tema penelusuran menggunakan AssetGroupSignal.

Anda dapat melampirkan satu atau beberapa resource AdGroupCriterion atau CampaignCriterion ke grup iklan atau kampanye. Ini mewakili kriteria yang menentukan cara pemicuan iklan.

Ada banyak jenis kriteria, seperti kata kunci, rentang usia, dan lokasi. Kriteria yang ditentukan di tingkat kampanye memengaruhi semua resource lain dalam kampanye. Anda juga dapat menentukan anggaran serta tanggal dan waktu mulai dan akhir untuk kampanye, atau untuk masing-masing iklan menggunakan AdGroupAd.start_date_time dan AdGroupAd.end_date_time.

Terakhir, Anda dapat melampirkan aset di tingkat akun, kampanye, grup iklan, atau grup aset. Aset memungkinkan Anda memberikan informasi tambahan ke iklan, seperti nomor telepon, alamat jalan, atau promosi. Lihat Ringkasan aset.

Resource

Resource merepresentasikan entitas dalam akun Google Ads Anda. Campaign dan AdGroup adalah dua contoh resource.

ID Objek

Setiap objek di Google Ads diidentifikasi berdasarkan ID-nya sendiri. Beberapa ID ini bersifat unik secara global di semua akun Google Ads, sementara ID lainnya hanya unik dalam cakupan terbatas.

Aturan ID ini dapat berguna saat mendesain penyimpanan lokal untuk objek Google Ads Anda.

Beberapa objek dapat digunakan untuk beberapa jenis entity. Dalam kasus tersebut, objek berisi kolom type yang menjelaskan isinya. Misalnya, AdGroupAd dapat merujuk ke objek seperti iklan penelusuran responsif, iklan hotel, atau iklan Peningkat Permintaan. Nilai ini dapat diakses melalui kolom AdGroupAd.ad.type, dan menampilkan nilai dalam enum AdType. Perhatikan bahwa mutabilitas dapat bervariasi menurut versi (misalnya, VideoResponsiveAdInfo di Ad dapat berubah di v24 dan yang lebih baru).

Nama resource

Setiap resource diidentifikasi secara unik oleh string resource_name yang menggabungkan resource dan induknya ke dalam jalur. Misalnya, nama resource kampanye memiliki format:

customers/customer_id/campaigns/campaign_id

Jadi, untuk kampanye dengan ID 987654 di akun Google Ads dengan ID pelanggan 1234567, resource_name-nya adalah:

customers/1234567/campaigns/987654

Layanan

Layanan memungkinkan Anda mengambil dan mengubah entitas Google Ads. Ada tiga jenis layanan: layanan modifikasi, pengambilan objek dan statistik, serta layanan pengambilan metadata.

Mengubah (memutasi) objek

Layanan khusus resource mengubah instance jenis resource terkait menggunakan permintaan mutate. Anda juga dapat menggunakan GoogleAdsService.Mutate untuk melakukan mutasi atomik di beberapa jenis resource dalam satu permintaan (seperti membuat anggaran kampanye, kampanye, dan grup iklan secara bersamaan).

Contoh layanan khusus resource:

• CustomerService untuk mengubah pelanggan.

• CampaignService untuk mengubah kampanye.

• AdGroupService untuk mengubah grup iklan.

Setiap permintaan mutate harus menyertakan objek operation yang sesuai. Misalnya, metode CampaignService.MutateCampaigns mengharapkan satu atau beberapa instance CampaignOperation. Lihat Mengubah objek untuk mengetahui pembahasan mendetail tentang operasi.

Mutasi serentak

Objek Google Ads tidak dapat diubah secara bersamaan oleh lebih dari satu sumber. Hal ini dapat menyebabkan error muncul jika Anda memiliki beberapa pengguna yang memperbarui objek yang sama dengan aplikasi Anda, atau jika Anda mengubah objek Google Ads secara paralel menggunakan beberapa thread. Hal ini mencakup memperbarui objek dari beberapa thread dalam aplikasi yang sama, atau dari aplikasi yang berbeda (misalnya, aplikasi Anda dan sesi UI Google Ads yang bersamaan).

API tidak menyediakan cara untuk mengunci objek sebelum memperbarui; jika dua sumber mencoba mengubah objek secara bersamaan, API akan memunculkan DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutasi asinkron versus sinkron

Metode perubahan Google Ads API bersifat sinkron. Panggilan API hanya menampilkan respons setelah objek diubah, sehingga Anda harus menunggu respons untuk setiap permintaan. Meskipun pendekatan ini relatif mudah dikodekan, pendekatan ini dapat berdampak negatif pada penyeimbangan beban dan membuang-buang resource jika proses dipaksa menunggu panggilan selesai.

Pendekatan alternatifnya adalah mengubah objek secara asinkron menggunakan BatchJobService, yang melakukan batch operasi pada beberapa layanan tanpa menunggu penyelesaiannya. Setelah tugas batch dikirimkan, server Google Ads API akan menjalankan operasi secara asinkron, sehingga proses dapat melakukan operasi lain. Anda dapat memeriksa status tugas secara berkala untuk mengetahui apakah tugas telah selesai.

Lihat Panduan pemrosesan batch untuk mengetahui informasi selengkapnya tentang pemrosesan asinkron.

Validasi mutasi

Sebagian besar permintaan perubahan dapat divalidasi tanpa benar-benar mengeksekusi panggilan terhadap data sebenarnya. Anda dapat menguji permintaan untuk parameter yang tidak ada dan nilai kolom yang salah tanpa benar-benar menjalankan operasi.

Untuk menggunakan fitur ini, tetapkan kolom boolean validate_only opsional permintaan ke true. Permintaan divalidasi sepenuhnya seolah-olah akan dieksekusi, tetapi eksekusi akhir dilewati. Jika tidak ada error, respons akan ditampilkan tanpa hasil yang diubah (results kosong). Jika validasi gagal, permintaan akan gagal dengan error RPC GoogleAdsFailure secara default (partial_failure = false), atau menampilkan respons normal dengan error khusus operasi di partial_failure_error saat partial_failure = true.

validate_only sangat berguna dalam menguji iklan untuk mengetahui apakah ada pelanggaran kebijakan umum. Iklan akan otomatis ditolak jika melanggar kebijakan seperti memiliki kata, tanda baca, kapitalisasi, atau panjang tertentu. Satu iklan yang buruk dapat menyebabkan seluruh batch gagal. Menguji iklan baru dalam permintaan validate_only dapat mengungkapkan pelanggaran semacam itu. Lihat contoh kode untuk menangani error pelanggaran kebijakan untuk melihat cara kerjanya.

Mendapatkan objek dan statistik performa

GoogleAdsService adalah layanan tunggal dan terpadu untuk mengambil objek dan statistik performa.

Semua permintaan Search dan SearchStream untuk GoogleAdsService memerlukan kueri yang menentukan resource yang akan dikueri, atribut resource dan metrik performa yang akan diambil, predikat yang akan digunakan untuk memfilter permintaan, dan segmen yang akan digunakan untuk mengelompokkan statistik performa lebih lanjut. Untuk mengetahui informasi selengkapnya tentang format kueri, lihat panduan Bahasa Kueri Google Ads.

Mengambil metadata

GoogleAdsFieldService mengambil metadata tentang resource di Google Ads API, seperti atribut yang tersedia untuk resource dan jenis datanya. Lihat Panduan metadata resource untuk mengetahui detail tentang membuat kueri layanan ini.

Layanan ini memberikan informasi yang diperlukan dalam menyusun kueri ke GoogleAdsService. Untuk mempermudah, informasi yang ditampilkan oleh GoogleAdsFieldService juga tersedia di dokumentasi referensi kolom.