Bahasa Kueri Google Ads

Bahasa Kueri Google Ads dapat meminta Google Ads API untuk

Resource dan atribut, segmen, dan metrik terkait menggunakan
GoogleAdsService Penelusuran 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, responsnya 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 diminta dengan detail spesifik tentang kompatibilitas dan jenisnya.

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

Membuat kueri untuk atribut resource

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

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

Kueri ini diurutkan menurut ID kampanye. Setiap GoogleAdsRow yang dihasilkan akan mewakili objek campaign yang diisi dengan kolom yang dipilih (termasuk yang diberikan resource_name kampanye).

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

Membuat kueri metrik

Bersama 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 hanya memfilter kampanye yang memiliki status PAUSED dan memiliki lebih dari 1.000 tayangan, saat mengurutkan berdasarkan ID kampanye. Setiap GoogleAdsRow yang dihasilkan akan memiliki kolom metrics yang diisi dengan metrik yang dipilih.

Untuk mengetahui daftar metrik yang dapat diminta, baca dokumentasi Metrics.

Membuat kueri untuk segmen

Bersama 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 membuat kueri untuk metrik, kueri ini hanya memfilter kampanye yang memiliki status PAUSED dan memiliki lebih dari 1.000 tayangan. Namun, kueri ini menyegmentasikan data menurut tanggal. Ini mengarah ke setiap GoogleAdsRow yang dihasilkan yang mewakili tuple kampanye dan tanggal Segment. Penting untuk diperhatikan bahwa segmentasi memisahkan metrik yang dipilih, yang mengelompokkan menurut setiap segmen dalam klausa SELECT.

Untuk daftar segmen yang dapat diminta, baca dokumentasi Segments.

Dalam kueri untuk resource tertentu, Anda mungkin dapat bergabung dengan resource terkait lainnya jika tersedia. Resource terkait ini dikenal sebagai "resource 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.

Bermutasi berdasarkan hasil kueri

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

  1. Jalankan kueri untuk semua kampanye yang saat ini PAUSED dan memiliki tayangan 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 untuk memperbaruinya.

Metadata kolom

Kueri yang dikirim ke GoogleAdsFieldService dimaksudkan untuk mengambil metadata kolom. Informasi ini dapat digunakan untuk memahami bagaimana kolom dapat digunakan bersama dalam kueri. Karena data tersedia dari API dan memberikan metadata yang diperlukan untuk memvalidasi atau membuat kueri, hal ini memungkinkan developer melakukannya secara terprogram. Berikut adalah kueri standar 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).

Untuk mengetahui daftar kolom yang dapat diminta, baca dokumentasi GoogleAdsField.

Contoh kode

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