Bahasa Kueri Google Ads

Tips: Gunakan Pembuat Kueri Interaktif untuk membuat dan memvalidasi kueri GAQL Anda.

Terminologi utama

Resource

Entitas di Google Ads, seperti campaign atau ad_group.

Segmen

Dimensi yang digunakan untuk mengelompokkan data, seperti segments.date atau segments.device. Jika segmen disertakan dalam klausa SELECT dengan metrik, metrik akan dibagi menurut segmen.

Metrik

Pengukuran performa, seperti metrics.impressions atau metrics.clicks.

Resource yang Diatribusikan

Resource yang digabungkan secara implisit ke resource utama dalam klausa FROM, sehingga Anda dapat memilih atributnya bersama dengan atribut resource utama.

Membuat kueri untuk informasi resource atau metadata

Bahasa Kueri Google Ads dapat mengkueri Google Ads API untuk jenis informasi berikut:

• Resource dan atribut, segmen, serta metrik terkaitnya menggunakan GoogleAdsService Search atau SearchStream: Hasil dari kueri GoogleAdsService adalah daftar instance GoogleAdsRow, dengan setiap GoogleAdsRow mewakili resource.

  Jika ada atribut atau metrik yang diminta, baris juga akan menyertakan kolom tersebut. Jika ada segmen yang diminta, respons juga akan menampilkan baris tambahan untuk setiap tuple resource segmen.

• Metadata tentang kolom dan resource yang tersedia di GoogleAdsFieldService: Layanan ini menyediakan katalog kolom yang dapat dikueri dengan spesifikasi tentang kompatibilitas dan jenisnya.

  Hasil dari kueri GoogleAdsFieldService adalah daftar instance GoogleAdsField, dengan setiap GoogleAdsField berisi detail tentang kolom yang diminta.

Untuk mengetahui detail selengkapnya tentang struktur kueri, lihat Struktur kueri dan Tata bahasa Google Ads Query Language.

Membuat kueri untuk atribut resource

Berikut adalah contoh kueri dasar untuk atribut resource kampanye yang mengilustrasikan cara menampilkan ID, nama, dan status kampanye:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Kueri ini mengurutkan berdasarkan ID kampanye. Setiap GoogleAdsRow yang dihasilkan mewakili objek campaign yang diisi dengan kolom yang dipilih, termasuk resource_name kampanye.

Untuk mengetahui kolom lain yang tersedia untuk kueri kampanye, lihat dokumentasi referensi Campaign.

Membuat kueri untuk metrik

Selain atribut yang dipilih untuk resource tertentu, Anda juga dapat membuat kueri untuk metrik terkait:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Kueri ini memfilter hanya kampanye yang memiliki status PAUSED dan memiliki lebih dari 1.000 tayangan iklan, sekaligus mengurutkan berdasarkan ID kampanye. Setiap GoogleAdsRow yang dihasilkan akan memiliki kolom metrics yang diisi dengan metrik yang dipilih.

Untuk mengetahui daftar metrik yang dapat dikueri, lihat dokumentasi Metrics.

Kueri untuk segmen

Selain atribut yang dipilih untuk resource tertentu, Anda juga dapat membuat kueri untuk segmen terkait:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

Serupa dengan kueri untuk metrik, kueri ini memfilter hanya kampanye yang memiliki status PAUSED dan memiliki lebih dari 1.000 tayangan iklan. Namun, kueri ini menyegmentasikan data menurut tanggal. Hal ini menyebabkan setiap GoogleAdsRow yang dihasilkan mewakili tuple kampanye dan segmen tanggal. Segmentasi membagi metrik yang dipilih, mengelompokkan menurut setiap segmen dalam klausa SELECT.

Untuk mengetahui daftar segmen yang dapat dikueri, lihat dokumentasi Segments.

Membuat kueri untuk atribut resource terkait

Dalam kueri untuk resource tertentu, Anda mungkin dapat menggabungkan dengan resource terkait lainnya jika tersedia. Referensi terkait ini dikenal sebagai "referensi yang diatribusikan". Anda dapat menggabungkan resource yang diatribusikan secara implisit dengan memilih atribut dalam kueri Anda.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Kueri ini tidak hanya memilih atribut kampanye, tetapi juga mengambil atribut terkait dari setiap kampanye yang dipilih. Setiap GoogleAdsRow yang dihasilkan mewakili objek campaign yang diisi dengan atribut kampanye yang dipilih, serta atribut strategi bidding yang dipilih bidding_strategy.name.

Untuk mengetahui resource yang diatribusikan yang tersedia untuk kueri kampanye, lihat dokumentasi referensi Campaign.

Praktik terbaik

• Pilih hanya kolom yang Anda perlukan untuk menghindari waktu tunggu dan waktu respons yang lama.
• Gunakan LIMIT selama pengembangan dan pengujian untuk menghindari pemrosesan set hasil yang besar.
• Terapkan filter dalam klausa WHERE untuk meminimalkan transfer data dan ukuran respons.
• Gunakan GoogleAdsFieldService untuk memeriksa kompatibilitas kolom dan jenis data sebelum membuat kueri yang kompleks.
• Perlu diingat bahwa beberapa kolom, terutama yang melibatkan data dalam jumlah besar atau penghitungan yang kompleks, dapat meningkatkan biaya kueri.

Mengubah berdasarkan hasil kueri

Saat membuat kueri untuk resource tertentu, Anda dapat langsung mengambil hasil yang ditampilkan sebagai objek, mengubahnya, dan mengirimkannya kembali ke metode mutasi di layanan resource tersebut. Berikut adalah contoh alur kerja:

1. Jalankan kueri untuk semua kampanye PAUSED yang memiliki tayangan iklan lebih dari 1.000.
2. Dapatkan objek Campaign dari kolom campaign setiap GoogleAdsRow dalam respons.
3. Ubah status setiap kampanye dari PAUSED menjadi ENABLED.
4. Panggil CampaignService.MutateCampaigns dengan kampanye yang diubah dan FieldMask yang sesuai untuk memperbaruinya.

Catatan: Saat memperbarui resource yang diambil dari kueri, tentukan FieldMask (atau gunakan utilitas field mask bawaan library klien Anda) sehingga hanya kolom yang diubah yang diperbarui, sehingga menghindari error READ_ONLY_FIELD atau IMMUTABLE_FIELD, atau menimpa atribut lain secara tidak sengaja.

Metadata kolom

Kueri yang dikirim ke GoogleAdsFieldService dimaksudkan untuk mengambil metadata kolom. Informasi ini dapat digunakan untuk memahami cara kolom dapat digunakan bersama dalam kueri. Karena data tersedia dari API dan menyediakan metadata yang diperlukan untuk memvalidasi atau membuat kueri, developer dapat melakukannya secara terprogram. Berikut adalah kueri umum untuk metadata:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Anda dapat mengganti <INSERT_RESOURCE_OR_FIELD> dalam kueri ini dengan resource (seperti customer atau campaign) atau kolom (seperti campaign.id, metrics.impressions, atau ad_group.id).

Poin Penting: Perhatikan bahwa tidak ada klausa FROM dalam kueri ini.

Untuk mengetahui daftar kolom yang dapat dikueri, lihat dokumentasi GoogleAdsField.

Perbedaan khusus versi

Meskipun sintaksis, klausa, dan operator Bahasa Kueri Google Ads identik di semua versi Google Ads API yang didukung (v23, v24, v25, dan v26), katalog resource, segmen, metrik, dan perilaku pelaporan yang dapat dikueri berbeda menurut versi utama. Buat kueri GoogleAdsFieldService di endpoint versi API target untuk memeriksa kolom dan aturan kompatibilitas untuk versi tersebut:

• Tampilan aset perluasan URL final:
  • Dukungan kampanye Shopping (v26 dan yang lebih baru): final_url_expansion_asset_view mendukung kampanye Shopping (campaign.advertising_channel_type = 'SHOPPING') selain kampanye Performa Maksimal dan Penelusuran. Untuk kampanye Shopping, Anda dapat memilih dan memfilter menurut kolom ad_group, tetapi Anda tidak dapat memilih kolom asset_group.
  • Metrik yang dapat dipilih (v25 dan yang lebih baru): Membuat kueri final_url_expansion_asset_view akan menampilkan semua metrik yang dapat dipilih untuk tampilan. Di v24 dan versi sebelumnya, respons hanya menyertakan metrics.conversions dan metrics.conversions_value untuk kampanye Performa Maksimal dan metrics.impressions untuk kampanye Penelusuran.
• Resource sasaran siklus proses: Di v25 dan yang lebih baru, semua sasaran siklus proses (Akuisisi Pelanggan Baru, Retensi Pelanggan, dan Retensi Loyalitas) dikueri dari resource goal dan campaign_goal_config terpadu, menggantikan customer_lifecycle_goal dan campaign_lifecycle_goal (yang digunakan untuk sasaran Akuisisi Pelanggan Baru di v24 dan yang lebih lama, bersama dengan goal dan campaign_goal_config untuk sasaran Retensi Pelanggan).
• Pelaporan produk Shopping untuk kampanye Aplikasi: Di v24 dan yang lebih baru, resource shopping_product menampilkan baris produk untuk kampanye Aplikasi selain kampanye Shopping, Performa Maksimal, Peningkat Permintaan, dan Video (di v23, kampanye Aplikasi dikecualikan dari hasil shopping_product).
• Resource, segmen, dan metrik khusus versi:
  • v26 dan yang lebih baru: Menyertakan resource search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property, dan metrik Search Lift (seperti metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros, dan metrics.search_lift_impressions).
  • v25 dan yang lebih baru: Mencakup resource pengukuran peningkatan (seperti lift_measurement_config), segmen seperti segments.ad_sub_format_type dan segments.loyalty_membership, serta metrik engagement YouTube (metrics.youtube_likes, metrics.youtube_comments, dan metrics.youtube_shares). Menghapus local_services_lead.contact_details.email (yang dapat dipilih di v24 dan yang lebih lama).
  • v24 dan yang lebih baru: Menyertakan resource cart_data_sales_view, segments.conversion_attribution_event_type di shopping_performance_view, segments.mobile_device_platform, dan segments.ad_network_type di performance_max_placement_view. Menghapus campaign.video_brand_safety_suitability (diganti dengan customer.video_brand_safety_suitability), segments.ad_sub_network_type di campaign_budget, dan segments.click_type di ad_group_asset, campaign_asset, dan customer_asset (yang hanya dapat dipilih di v23).
• Kode error lihat balik tanggal terperinci: Kueri yang menyegmentasikan menurut segments.date, segments.week, atau segments.hour (atau memfilter rentang tanggal sub-bulanan) di luar periode lihat balik 37 bulan akan menampilkan DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED di v24 dan yang lebih baru (atau DateRangeError.UNKNOWN di v23). Lihat Rentang tanggal untuk mengetahui detailnya.

Contoh kode

Library klien memiliki contoh penggunaan Bahasa Kueri Google Ads di GoogleAdsService. Folder operasi dasar memiliki contoh seperti GetCampaigns, GetKeywords, dan SearchForGoogleAdsFields.