Struktur API

Video: Lihat workshop Layanan dan Referensi dari workshop 2019

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

Hierarki objek

Akun Google Ads dapat dianggap sebagai hierarki objek.

  • Resource tingkat teratas akun adalah pelanggan.

  • Setiap akun berisi satu atau beberapa kampanye yang aktif.

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

  • Setiap AdGroup berisi satu atau beberapa iklan grup iklan. AdGroupAd menunjukkan iklan yang Anda jalankan.

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

Ada banyak jenis kriteria, seperti kata kunci, rentang usia, dan lokasi. Kriteria yang ditentukan di tingkat kampanye memengaruhi semua resource lain dalam kampanye tersebut. Anda juga dapat menentukan anggaran dan tanggal seluruh kampanye.

Terakhir, Anda dapat melampirkan ekstensi di tingkat akun, kampanye, atau grup iklan. Ekstensi memungkinkan Anda memberikan informasi tambahan ke iklan, seperti nomor telepon, alamat, atau promosi.

Resource

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

ID objek

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

ID Objek Cakupan Keunikan Unik Secara Global?
ID Anggaran Global Ya
ID Kampanye Global Ya
Nomor Grup Iklan Global Ya
ID iklan Ad Group Tidak, tetapi pasangan (AdGroupId, AdId) bersifat unik secara global
ID Kriteria GrupIklan Ad Group Tidak, tetapi pasangan (AdGroupId, CriterionId) bersifat unik secara global
ID Kriteria Kampanye Kampanye Tidak, tetapi pasangan (CampaignId, CriterionId) bersifat unik secara global
Ekstensi Iklan Kampanye Tidak, tetapi pasangan (CampaignId, AdExtensionId) bersifat unik secara global
ID Feed Global Ya
ID Elemen Feed Global Ya
ID Atribut Feed Feed Tidak
ID Pemetaan Feed Global Ya
ID Label Global Ya
ID DaftarPengguna Global Ya

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

Beberapa objek dapat digunakan untuk beberapa jenis entity. Dalam kasus tersebut, objek berisi kolom type yang mendeskripsikan kontennya. Misalnya, AdGroupAd dapat merujuk ke iklan teks, iklan hotel, iklan lokal, dll. Nilai ini dapat diakses melalui kolom AdGroupAd.ad.type, dan menampilkan nilai dalam enum AdType.

Nama fasilitas

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 akan menjadi:

customers/1234567/campaigns/987654

Layanan

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

Mengubah (mutasi) objek

Layanan ini mengubah instance jenis resource terkait menggunakan permintaan mutate. Adaptor ini juga menyediakan permintaan get yang mengambil satu instance resource, yang dapat berguna untuk memeriksa struktur resource.

Contoh layanan:

Setiap permintaan mutate harus menyertakan objek operation yang sesuai. Misalnya, metode CampaignService.MutateCampaigns mengharapkan satu atau beberapa instance CampaignOperation. Lihat Mengubah dan Memeriksa Objek untuk pembahasan lebih detail tentang operasi.

Mutasi serentak

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

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

Mutasi asinkron versus sinkron

Metode mutasi Google Ads API bersifat sinkron. Panggilan API hanya menampilkan respons setelah objek dimutasi, sehingga Anda harus menunggu respons untuk setiap permintaan. Meskipun pendekatan ini relatif mudah untuk dikodekan, pendekatan ini dapat berdampak negatif pada load balancing dan menyia-nyiakan resource jika proses dipaksa untuk menunggu panggilan selesai.

Pendekatan alternatifnya adalah memutasikan objek secara asinkron menggunakan BatchJobService, yang menjalankan batch operasi pada beberapa layanan tanpa menunggu penyelesaiannya. Setelah tugas batch dikirim, server Google Ads API menjalankan operasi secara asinkron, sehingga membebaskan proses untuk melakukan operasi lain. Anda dapat memeriksa status pekerjaan secara berkala untuk menyelesaikan.

Lihat Panduan Pemrosesan Batch untuk informasi selengkapnya tentang pemrosesan asinkron.

Mutasi validasi

Sebagian besar permintaan mutasi dapat divalidasi tanpa benar-benar menjalankan panggilan pada data sungguhan. 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 ke true. Selanjutnya, permintaan akan sepenuhnya divalidasi seolah-olah akan dijalankan, tetapi eksekusi akhir akan dilewati. Jika tidak ditemukan error, respons kosong akan ditampilkan. Jika validasi gagal, pesan error dalam respons akan menunjukkan poin kegagalan.

validate_only sangat berguna dalam menguji iklan untuk pelanggaran kebijakan umum. Iklan akan ditolak secara otomatis jika melanggar kebijakan seperti memiliki kata, tanda baca, kapitalisasi, atau panjang yang spesifik. Satu iklan yang buruk dapat menyebabkan seluruh kelompok gagal. Menguji iklan baru dalam permintaan validate_only dapat mengungkapkan pelanggaran tersebut. 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 untuk kueri, atribut resource, dan metrik performa yang akan diambil, predikat yang digunakan untuk memfilter permintaan, dan segmen yang akan digunakan untuk mengelompokkan statistik performa lebih lanjut. Untuk 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.

Layanan ini memberikan informasi yang Anda perlukan dalam membuat kueri ke GoogleAdsService. Untuk memudahkan, informasi yang ditampilkan oleh GoogleAdsFieldService juga tersedia dalam dokumentasi referensi kolom.