Mengambil objek

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

  • Mengambil atribut spesifik objek.
  • Mengambil metrik performa untuk objek berdasarkan rentang tanggal.
  • Mengurutkan objek berdasarkan atributnya.
  • Gunakan kondisi untuk menunjukkan objek mana 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 kumpulan hasil yang besar (lebih dari 10.000 baris). Cara ini direkomendasikan jika aplikasi Anda mendownload seluruh kumpulan hasil atau memproses baris sebagai aliran.
  • 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 penomoran halaman versus streaming.

Buat permintaan

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

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

Bergantung pada metode, permintaan juga mendukung kolom khusus metode:

  • SearchGoogleAdsStreamRequest (SearchStream saja):
  • SearchGoogleAdsRequest (Search saja):
    • page_token opsional untuk mengambil batch hasil berikutnya saat menggunakan penomoran halaman (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 menjalankannya

Untuk mengetahui 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 dalam SearchGoogleAdsResponse yang di-paging).

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 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 klausul SELECT-nya tidak menyertakan ad_group_criterion.status. Demikian pula, atribut campaign baris tidak 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; sehingga baris harus dilihat sebagai objek, bukan baris tetap dalam tabel.

Jenis enum UNKNOWN dan UNSPECIFIED

Resource yang ditampilkan dengan nilai enum UNKNOWN tidak sepenuhnya didukung 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 di 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.
  • Objek baru dengan jenis UNKNOWN dapat muncul kapan saja. Objek ini kompatibel dengan versi sebelumnya karena nilai enum UNKNOWN ada di setiap enum dalam API. Resource ditampilkan dengan UNKNOWN sehingga Anda memiliki tampilan akurat tentang metrik performa keseluruhan akun Anda.
  • UNKNOWN resource dapat memiliki metrik mendetail yang dilampirkan dan dapat dikueri.
  • UNKNOWN biasanya terlihat sepenuhnya di UI Google Ads.
  • Resource UNKNOWN umumnya tidak dapat diubah melalui API.

Segmentasi

Responsnya 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 secara implisit disegmentasikan 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 berbeda dari kolom campaign.status.

Sebelumnya
Mengubah objek
Berikutnya
Metadata resource