Mengambil objek

Tujuan: Memahami cara mengambil objek dan statistik performa menggunakan GoogleAdsService. Untuk konsep pelaporan, lihat panduan pelaporan.

GoogleAdsService adalah layanan pelaporan dan pengambilan objek terpadu dari Google Ads API. Layanan ini memiliki metode yang:

• Mengambil atribut objek tertentu.
• Mengambil metrik performa untuk objek berdasarkan rentang tanggal.
• Mengurutkan objek berdasarkan atributnya.
• Gunakan kondisi untuk menunjukkan objek yang ingin Anda tampilkan dalam respons.
• Membatasi jumlah objek yang ditampilkan.

GoogleAdsService dapat menampilkan hasil dengan dua cara:

• GoogleAdsService.SearchStream menampilkan semua baris dalam satu respons streaming, yang lebih efisien untuk set hasil yang besar (lebih dari 10.000 baris). Hal ini direkomendasikan jika aplikasi Anda mendownload kumpulan hasil lengkap atau memproses baris sebagai aliran data.
• GoogleAdsService.Search memecah respons besar menjadi halaman hasil yang dapat dikelola. Hal ini berguna jika aplikasi interaktif Anda menampilkan halaman hasil satu per satu.

Pelajari lebih lanjut paging versus streaming.

Buat permintaan

GoogleAdsService.SearchStream mengharapkan SearchGoogleAdsStreamRequest, dan GoogleAdsService.Search mengharapkan SearchGoogleAdsRequest. Kedua jenis permintaan mencakup:

• customer_id
• query Bahasa Kueri Google Ads yang menunjukkan resource yang akan dikueri, atribut, segmen, dan metrik yang akan diambil, serta kondisi yang akan digunakan untuk membatasi objek yang ditampilkan

Bergantung pada metodenya, permintaan juga mendukung kolom khusus metode:

• SearchGoogleAdsStreamRequest (khusus SearchStream):
  • summary_row_setting opsional untuk meminta baris ringkasan yang berisi metrik gabungan
• SearchGoogleAdsRequest (khusus Search):
  • page_token opsional untuk mengambil batch hasil berikutnya saat menggunakan paging (page_size ditetapkan pada 10.000 baris; menyetel page_size dalam permintaan akan menampilkan error RequestError.PAGE_SIZE_NOT_SUPPORTED)
  • Pesan search_settings opsional untuk mengonfigurasi return_summary_row, return_total_results_count, dan omit_results
  • Boolean validate_only opsional untuk memvalidasi kueri tanpa mengeksekusinya

Untuk informasi selengkapnya tentang Bahasa Kueri Google Ads, lihat panduan Bahasa Kueri Google Ads.

Memproses respons

GoogleAdsService menampilkan daftar objek GoogleAdsRow (baik di dalam batch SearchGoogleAdsStreamResponse yang di-streaming atau di SearchGoogleAdsResponse yang diberi nomor halaman).

Setiap GoogleAdsRow mewakili objek yang ditampilkan oleh kueri, dan terdiri dari sekumpulan atribut yang diisi berdasarkan kolom yang diminta dalam klausa SELECT. Atribut yang tidak disertakan dalam klausa SELECT tidak akan diisi pada objek GoogleAdsRow dalam respons.

Misalnya, meskipun ad_group_criterion memiliki atribut status, kolom status dari atribut ad_group_criterion baris tidak diisi dalam respons untuk kueri yang klausa SELECT-nya tidak menyertakan ad_group_criterion.status. Demikian pula, atribut campaign baris tidak akan diisi jika klausa SELECT tidak menyertakan kolom apa pun dari resource campaign.

Setiap GoogleAdsRow dapat memiliki atribut dan metrik yang berbeda dari baris lain dalam set hasil yang sama; jadi baris harus dilihat sebagai objek, bukan baris tetap dari tabel.

Jenis enum UNKNOWN dan UNSPECIFIED

Resource yang ditampilkan dengan nilai enum UNKNOWN tidak didukung sepenuhnya dalam versi API tersebut, sedangkan UNSPECIFIED menunjukkan bahwa kolom enum belum ditetapkan atau tidak diminta dalam klausa SELECT. Resource dengan nilai enum UNKNOWN mungkin telah dibuat melalui antarmuka lain seperti UI Google Ads. Anda dapat memilih metrik saat resource memiliki jenis UNKNOWN, tetapi Anda tidak dapat mengubah resource melalui API. Contohnya adalah jenis kampanye atau iklan yang tersedia di UI, tetapi tidak didukung dalam versi API yang Anda kueri.

Berikut beberapa pertimbangan yang perlu diperhatikan:

• Resource dengan jenis UNKNOWN dapat didukung di versi API yang lebih baru atau tetap UNKNOWN tanpa batas waktu.
• Objek baru dengan jenis UNKNOWN dapat muncul kapan saja. Objek ini kompatibel dengan versi lama karena nilai enum UNKNOWN ada di setiap enum dalam API. Resource ditampilkan dengan UNKNOWN sehingga Anda memiliki tampilan yang akurat tentang metrik performa keseluruhan akun Anda.
• Resource UNKNOWN dapat memiliki metrik mendetail yang dilampirkan dan dapat dikueri.
• Resource UNKNOWN biasanya terlihat sepenuhnya di UI Google Ads.
• Resource UNKNOWN umumnya tidak dapat diubah melalui API.

Segmentasi

Respons berisi satu GoogleAdsRow untuk setiap kombinasi berikut:

• Instance resource utama yang ditentukan dalam klausa FROM
• Nilai setiap kolom segments yang dipilih

Misalnya, respons untuk kueri yang memilih FROM campaign dan memiliki segments.ad_network_type dan segments.date dalam klausa SELECT berisi satu baris untuk setiap kombinasi berikut:

• campaign
• segments.ad_network_type
• segments.date

Hasil disegmentasikan secara implisit oleh setiap instance resource utama, bukan oleh nilai setiap kolom yang dipilih. Misalnya,

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

menghasilkan satu baris per kampanye, bukan satu baris per nilai unik kolom campaign.status.

Catatan: Ketersediaan segmen dapat berbeda di berbagai versi API. Misalnya, segments.click_type di AdGroupAsset, CampaignAsset, dan CustomerAsset serta segments.ad_sub_network_type di campaign_budget hanya dapat dipilih di v23 dan yang lebih lama; segments.ad_network_type di PerformanceMaxPlacementView tersedia di v24 dan yang lebih baru; segments.ad_sub_format_type dan segments.loyalty_membership tersedia di v25 dan yang lebih baru; serta segments.search_lift_keyword_bundle dan segments.search_property tersedia di v26 dan yang lebih baru. Gunakan GoogleAdsFieldService untuk memverifikasi kompatibilitas segmen untuk versi API yang Anda kueri.