Video: Lihat diskusi 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 entitas Google Ads, sedangkan layanan mengambil dan memanipulasi entitas Google Ads.
Hierarki objek
Akun Google Ads dapat dilihat sebagai hierarki objek.
Resource tingkat atas akun adalah pelanggan.
Setiap pelanggan berisi satu atau beberapa kampanye aktif.
Setiap kampanye berisi satu atau beberapa grup iklan, yang digunakan untuk mengelompokkan iklan ke dalam koleksi logis.
Iklan grup iklan menunjukkan iklan yang sedang Anda jalankan. 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.
Anda dapat menyertakan satu atau beberapa AdGroupCriterion
atau CampaignCriterion
ke grup iklan atau
kampanye. Parameter 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. Anda juga dapat menentukan anggaran dan tanggal untuk seluruh kampanye.
Terakhir, Anda dapat menambahkan ekstensi di tingkat akun, kampanye, atau grup iklan. Ekstensi memungkinkan Anda memberikan informasi tambahan ke iklan, seperti nomor telepon, alamat, atau promosi.
Referensi
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, sementara ID 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 | Grup Iklan | Tidak, tetapi pasangan (AdGroupId , AdId ) bersifat unik secara global |
ID Kriteria GrupIklan | Grup Iklan | 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 Item 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 Anda.
Beberapa objek dapat digunakan untuk beberapa jenis entity. Dalam kasus seperti itu, objek
berisi kolom type
yang menjelaskan kontennya. Misalnya,
AdGroupAd
dapat merujuk ke objek seperti iklan teks,
iklan hotel, atau iklan lokal. Nilai ini dapat diakses melalui
kolom AdGroupAd.ad.type
, dan menampilkan nilai dalam
enum AdType
.
Nama resource
Setiap resource diidentifikasi secara unik oleh string resource_name
yang
menggabungkan resource dan induknya ke dalam jalur. Misalnya, nama resource kampanye memiliki bentuk:
customers/customer_id/campaigns/campaign_id
Jadi untuk kampanye dengan ID 987654
di akun Google Ads dengan ID pelanggan 1234567
, resource_name
adalah:
customers/1234567/campaigns/987654
Layanan
Layanan memungkinkan Anda mengambil dan mengubah entitas Google Ads Anda. Ada tiga jenis layanan: modifikasi, pengambilan objek dan statistik, serta layanan pengambilan metadata.
Mengubah (memutasikan) objek
Layanan ini memodifikasi instance jenis resource terkait menggunakan permintaan
mutate
. Objek ini juga menyediakan permintaan get
yang mengambil satu instance resource, yang dapat berguna untuk memeriksa struktur resource.
Contoh layanan:
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 dan Memeriksa Objek untuk diskusi mendetail tentang operasi.
Mutasi serentak
Objek Google Ads tidak dapat diubah secara serentak oleh lebih dari satu sumber. Hal ini dapat menyebabkan error jika ada beberapa pengguna yang mengupdate objek yang sama dengan aplikasi Anda, atau jika Anda mengubah objek Google Ads secara paralel menggunakan beberapa thread. Hal ini termasuk mengupdate objek dari beberapa thread di aplikasi yang sama, atau dari aplikasi yang berbeda (misalnya, aplikasi Anda 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 diubah, sehingga Anda harus menunggu respons terhadap setiap permintaan. Meskipun pendekatan ini relatif mudah untuk dibuat kode, pendekatan ini dapat berdampak negatif pada load balancing dan pemborosan resource jika proses terpaksa menunggu panggilan selesai.
Pendekatan alternatifnya adalah memutasikan objek secara asinkron menggunakan
BatchJobService
, yang menjalankan batch
operasi di beberapa layanan tanpa menunggu selesai. Setelah tugas batch dikirim, server Google Ads API akan mengeksekusi operasi secara asinkron, yang membebaskan proses untuk melakukan operasi lainnya. Anda dapat memeriksa status pekerjaan
secara berkala untuk penyelesaiannya.
Lihat panduan Batch Processing untuk mengetahui informasi selengkapnya mengenai pemrosesan asinkron.
Mutasi validasi
Sebagian besar permintaan mutasi dapat divalidasi tanpa benar-benar menjalankan panggilan pada data sebenarnya. Anda dapat menguji permintaan untuk parameter yang tidak ada dan nilai kolom yang salah tanpa benar-benar mengeksekusi operasi.
Untuk menggunakan fitur ini, tetapkan kolom boolean validate_only
opsional dalam permintaan ke
true
. Permintaan tersebut kemudian akan divalidasi sepenuhnya seolah-olah akan
dieksekusi, tetapi eksekusi akhir akan dilewati. Jika tidak ditemukan error, respons
kosong akan ditampilkan. Jika validasi gagal, pesan error dalam respons akan menunjukkan titik kegagalan.
validate_only
sangat berguna dalam menguji iklan untuk pelanggaran kebijakan umum. Iklan akan otomatis ditolak jika melanggar kebijakan, misalnya 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 tersebut. Lihat contoh kode untuk menangani
error pelanggaran kebijakan untuk melihat
cara kerjanya.
Dapatkan statistik objek dan performa
GoogleAdsService
adalah layanan tunggal dan terpadu
untuk mengambil statistik objek dan 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 digunakan untuk memfilter permintaan, dan segmen yang akan digunakan untuk
menguraikan statistik performa lebih lanjut. Untuk informasi lebih lanjut 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 diperlukan dalam membuat kueri ke
GoogleAdsService
. Untuk memudahkan, informasi yang ditampilkan oleh
GoogleAdsFieldService
juga tersedia
di dokumentasi referensi kolom.