Struktur API

ondemand_video Video: Lihat pembahasan Layanan dan Referensi dari workshop 2019

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

Hierarki objek

Akun Google Ads dapat dilihat sebagai hierarki objek.

• Sumber daya tingkat teratas akun adalah pelanggan.

• Setiap pelanggan berisi satu atau beberapa aktif kampanye.

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

• Iklan grup iklan mewakili iklan yang sedang berjalan. Kecuali untuk kampanye aplikasi yang hanya dapat memiliki satu iklan grup iklan per iklan grup iklan, setiap grup iklan berisi satu atau beberapa iklan grup iklan.

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

Ada banyak jenis kriteria, seperti kata kunci, rentang usia, dan lokasi. Kriteria yang ditentukan pada kampanye memengaruhi semua resource lain dalam kampanye. 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 ke iklan Anda, seperti nomor telepon, alamat, atau promosi.

Resource

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

ID Objek

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

Aturan ID ini dapat berguna saat merancang penyimpanan lokal untuk Google Ads Anda objek terstruktur dalam jumlah besar.

Beberapa objek dapat digunakan untuk beberapa jenis entity. Dalam kasus tersebut, objek berisi kolom type yang menjelaskan kontennya. Misalnya, AdGroupAd dapat merujuk pada objek seperti iklan teks, iklan hotel, atau iklan lokal. Nilai ini dapat diakses melalui AdGroupAd.ad.type, dan menampilkan nilai di kolom enum AdType.

Nama resource

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

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 Anda. Ada tiga jenis layanan: modifikasi, pengambilan objek dan statistik, serta pengambilan metadata layanan IT perusahaan mereka.

Mengubah (mutate) objek

Layanan ini mengubah instance dari jenis resource yang terkait menggunakan mutate permintaan. Modul tersebut juga menyediakan permintaan get yang mengambil satu resource instance, 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. Sebagai contoh, metode CampaignService.MutateCampaigns mengharapkan satu atau beberapa instance CampaignOperation. Lihat Mengubah dan Memeriksa Objek untuk diskusi operasi yang terperinci.

Mutasi serentak

Objek Google Ads tidak dapat diubah secara serentak oleh lebih dari satu sumber. Ini dapat menyebabkan error jika ada beberapa pengguna yang memperbarui objek yang sama dengan aplikasi Anda atau jika Anda mengubah objek Google Ads secara paralel menggunakan beberapa . Termasuk memperbarui objek dari beberapa thread dalam cara yang sama aplikasi tersebut, atau dari berbagai aplikasi (misalnya, aplikasi Anda dan sesi UI Google Ads secara bersamaan).

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

Mutasi asinkron versus sinkron

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

Pendekatan alternatifnya adalah memutasikan objek secara asinkron menggunakan BatchJobService, yang melakukan batch operasi di beberapa layanan tanpa menunggu penyelesaiannya. Setelah tugas batch dikirimkan, server Google Ads API mengeksekusi operasi secara asinkron, membebaskan proses untuk melakukan operasi lainnya. Anda dapat memeriksa secara berkala status pekerjaan yang telah selesai.

Lihat panduan Batch Processing untuk mengetahui informasi lebih lanjut dan pemrosesan asinkron.

Validasi mutasi

Sebagian besar permintaan mutasi dapat divalidasi tanpa benar-benar menjalankan panggilan dibandingkan data aktual. Anda dapat menguji permintaan apakah ada parameter yang tidak ada dan salah nilai isian tanpa benar-benar mengeksekusi operasinya.

Untuk menggunakan fitur ini, setel kolom boolean validate_only opsional permintaan ke true. Permintaan ini kemudian akan divalidasi sepenuhnya seolah-olah dieksekusi, tetapi eksekusi akhir dilewati. Jika tidak ditemukan error, kolom kosong ditampilkan. Jika validasi gagal, pesan {i>error<i} dalam respons akan menunjukkan titik kegagalan.

validate_only sangat berguna dalam menguji iklan untuk kebijakan umum pelanggaran data. Iklan akan otomatis ditolak jika melanggar kebijakan seperti memiliki kata-kata, tanda baca, kapitalisasi, atau panjang tertentu. Satu iklan yang tidak baik dapat menyebabkan seluruh batch gagal. Menguji iklan baru dalam validate_only dapat mengungkapkan pelanggaran tersebut. Lihat contoh kode untuk menangani error pelanggaran kebijakan untuk melihat dalam penerapannya.

Dapatkan objek dan statistik performa

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

Semua permintaan Search dan SearchStream untuk GoogleAdsService memerlukan kueri yang menentukan resource untuk atribut resource dan metrik performa yang akan diambil, predikat yang digunakan untuk memfilter permintaan, dan segmen yang akan digunakan untuk menguraikan statistik performa. 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 menyediakan informasi yang diperlukan dalam menyusun kueri untuk GoogleAdsService Untuk memudahkan, informasi yang ditampilkan oleh GoogleAdsFieldService juga tersedia di dokumentasi referensi kolom.