Baca bagian di bawah untuk mempelajari cara membuat laporan penelusuran di Search Ads 360 Reporting API.
Layanan penelusuran
Search Ads 360 Reporting API menyediakan layanan khusus untuk penelusuran dan pelaporan.
SearchAds360Service
adalah layanan pengambilan dan pelaporan objek terpadu
yang menyediakan dua metode penelusuran: SearchStream
dan Search
. Penelusuran
diteruskan dalam string kueri yang ditulis dalam Bahasa Kueri Search Ads 360. Anda dapat menentukan kueri untuk:
- Mengambil atribut tertentu dari objek.
- Mengambil metrik performa untuk objek berdasarkan rentang tanggal.
- Mengurutkan objek berdasarkan atributnya.
- Filter hasil Anda menggunakan kondisi yang menentukan objek yang akan ditampilkan
- Batasi jumlah objek yang ditampilkan.
Kedua metode penelusuran tersebut menampilkan semua baris yang cocok dengan kueri Anda. Misalnya, saat Anda mengambil campaign.id
, campaign.name
, dan metrics.clicks
, API akan menampilkan SearchAds360Row
yang berisi objek kampanye dengan kolom id
dan name
yang ditetapkan, serta objek metrics
dengan kolom clicks
-nya yang ditetapkan.
Metode penelusuran
SearchStream
Mengirim satu permintaan dan memulai koneksi persisten dengan Search Ads 360 Reporting API, berapa pun ukuran laporannya.
- Paket data akan segera didownload dan seluruh hasil disimpan dalam cache di buffer data.
- Kode Anda dapat mulai membaca data yang di-buffer tanpa harus menunggu seluruh aliran data selesai.
Search
Mengirim beberapa permintaan yang telah dipaginasi untuk mendownload seluruh laporan.
SearchStream
biasanya menawarkan performa yang lebih baik karena mengurangi
waktu jaringan bolak-balik yang diperlukan untuk meminta setiap halaman. Sebaiknya gunakan
SearchStream
untuk semua laporan yang memiliki lebih dari 10.000 baris. Tidak ada perbedaan
performa yang signifikan antara metode untuk laporan yang berukuran lebih kecil (<10.000 baris).
Metode yang Anda gunakan tidak memengaruhi kuota dan batas API Anda: satu kueri atau laporan akan dihitung sebagai satu operasi terlepas dari apakah hasilnya di-page atau di-streaming.
Contoh kueri penelusuran
Contoh kueri ini menampilkan data performa untuk sebuah akun selama 30 hari terakhir menurut kampanye, yang disegmentasikan menurut perangkat:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Buat permintaan
Untuk memberikan permintaan, Anda harus meneruskan string customer_id
dan query
ke antarmuka
SearchAds360Service.SearchStream
atau SearchAds360Service.Search
.
Permintaan terdiri dari POST
HTTP ke server Search Ads 360 Reporting API di salah satu URL berikut:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
Berikut adalah contoh lengkap definisi laporan untuk searchStream
yang diapit dalam
permintaan POST
HTTP:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
Memproses respons
SearchAds360Service
menampilkan daftar objek SearchAds360Row
.
Setiap SearchAds360Row
mewakili objek yang ditampilkan oleh kueri. Setiap objek terdiri dari sekumpulan atribut yang diisi berdasarkan kolom yang diminta dalam klausa SELECT
kueri. Atribut yang tidak disertakan dalam klausa SELECT
tidak diisi dalam objek dalam respons.
Misalnya, kueri di bawah ini hanya mengisi setiap objek SearchAds360Row
dengan campaign.id
, campaign.name
, dan campaign.status
. Atribut lain, seperti
campaign.engine_id
atau campaign.bidding_strategy_type
, dihilangkan.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
Dokumentasi referensi
Bagian Reference
menyertakan semua informasi yang Anda perlukan untuk menggunakan setiap artefak dengan benar. Ada
satu halaman untuk setiap resource, misalnya ad_group
dan
campaign
.
Halaman segments
dan metrics
mencantumkan semua kolom segmen dan metrik yang tersedia.
Beberapa resource, segmen, dan metrik tidak kompatibel serta tidak dapat digunakan bersama, sementara yang lain sepenuhnya kompatibel dan saling melengkapi. Setiap halaman resource menyertakan informasi berikut (jika tersedia dan sesuai) dan informasi lainnya:
- Resource yang diatribusikan
Untuk beberapa resource, Anda mungkin memiliki opsi untuk menggabungkan resource terkait secara implisit dengan memilih kolomnya bersama dengan kolom resource di klausa
FROM
. Misalnya, resourcecampaign
adalah resource atribusi dari resourcead_group
. Artinya, Anda dapat menyertakan kolom seperticampaign.id
dancampaign.bidding_strategy_type
dalam kueri saat menggunakanad_group
di klausaFROM
.Bagian Resource yang diatribusikan mencantumkan resource teratribusi yang tersedia. Tidak semua resource memiliki resource yang diatribusikan.
- Kolom kolom resource
Semua kolom fasilitas disertakan di kolom Kolom fasilitas. Setiap kolom resource ditautkan ke detail selengkapnya tentang kolom, termasuk deskripsi, kategori, jenis data, URL jenis, serta setelan yang dapat difilter, dapat dipilih, dapat diurutkan, dan berulang.
- Kolom segmen
Tidak semua kolom segmen dapat dipilih dengan resource yang ditentukan.
Kolom Segments mencantumkan kolom
segments
yang dapat Anda gunakan dalam klausaSELECT
yang sama dengan kolom resource. Setiap kolom ditautkan ke detail lengkap kolom tersebut, termasuk deskripsi, kategori, jenis data, jenis URL, serta setelan yang dapat difilter, dapat dipilih, dapat diurutkan, serta berulang. Jika menggunakan resource dalam klausaFROM
, Anda dapat menggunakan drop-down Ya/Tidak untuk memfilter segmen yang tidak tersedia.- Kolom metrik
Tidak semua kolom metrik dapat dipilih dengan resource yang ditentukan.
Kolom Metrik mencantumkan kolom
metrics
yang dapat Anda gunakan dalam klausaSELECT
yang sama dengan kolom resource. Setiap kolom ditautkan ke detail lengkap kolom tersebut, termasuk deskripsi, kategori, jenis data, jenis URL, serta setelan yang dapat difilter, dapat dipilih, dapat diurutkan, serta berulang. Jika Anda menggunakan resource dalam klausaFROM
, gunakan menu dropdown Ya/Tidak untuk memfilter metrik yang tidak tersedia.
- Mengelompokkan resource
Beberapa resource memiliki kolom resource segmentasi yang dapat Anda pilih saat resource berada dalam klausa
FROM
. Misalnya, jika Anda memilih kolom resourcecampaign
, seperticampaign.name
, saat menggunakancampaign_budget
dalam klausaFROM
,campaign.resource_name
akan otomatis ditampilkan dan disegmentasikan, karenacampaign
adalah resource segmentasi daricampaign_budget
.Bagian Referensi segmentasi mencantumkan referensi segmentasi yang tersedia. Tidak semua resource memiliki resource segmentasi.
- Dapat dipilih dengan
Beberapa kolom
segments
tidak kompatibel dengan resource, segmen, dan metrik lainnya.Halaman
segments
menyertakan Dapat dipilih dengan yang dapat diperluas untuk setiap kolomsegments
yang mencantumkan semua kolom resource yang kompatibel, kolommetrics
, dan kolomsegments
lainnya yang dapat Anda sertakan dalam klausaSELECT
.
Segmentasi
Anda dapat menyegmentasi hasil penelusuran dengan menambahkan kolom segments.FIELD_NAME
ke klausa SELECT
kueri Anda.
Misalnya, segments.device
dalam
kueri di bawah ini, menghasilkan laporan dengan baris untuk impressions
setiap
perangkat untuk resource yang ditentukan dalam klausa FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
Hasil yang ditampilkan oleh SearchAds360Service.SearchStream
akan terlihat seperti string JSON ini:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
Lihat segments
untuk mengetahui daftar kolom segmen yang tersedia dan dapat Anda gunakan.
Beberapa segmen
Anda dapat menentukan beberapa segmen di klausa SELECT
kueri Anda. Respons
berisi satu objek SearchAds360Row
untuk setiap kombinasi
instance resource utama yang ditentukan dalam klausa FROM
dan
value dari setiap kolom segment
yang dipilih.
Misalnya, kueri berikut akan menampilkan satu baris untuk setiap kombinasi campaign
, segments.ad_network_type
, dan segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Perhatikan bahwa hasil secara implisit disegmentasikan menurut setiap instance resource utama, tetapi bukan menurut nilai masing-masing kolom yang dipilih.
Contoh kueri berikut menghasilkan satu baris per kampanye, bukan satu baris per nilai yang berbeda dari kolom campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
Segmentasi implisit
Setiap laporan pada awalnya disegmentasikan berdasarkan resource yang ditentukan dalam klausa FROM
. Metrik disegmentasikan menurut kolom resource_name
resource ini
Contoh kueri ini otomatis menampilkan ad_group.resource_name
dan secara implisit menggunakannya untuk menyegmentasikan metrik di level ad_group
.
SELECT metrics.impressions
FROM ad_group
String JSON yang ditampilkan terlihat mirip dengan ini:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
Segmen tanggal inti
Anda dapat menggunakan segmen tanggal inti dalam klausa WHERE
untuk menentukan tanggal
atau jangka waktu.
Kolom segmen berikut dikenal sebagai segmen tanggal inti:
segments.date
, segments.week
, segments.month
, segments.quarter
, dan
segments.year
.
Contoh kueri ini menampilkan metrik clicks
kampanye selama 30 hari terakhir.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Kolom segmen tanggal inti adalah pengecualian terhadap aturan umum bahwa Anda tidak dapat menggunakan kolom segmen dalam klausa WHERE
, kecuali jika Anda juga menyertakan kolom tersebut dalam klausa SELECT
. Lihat Pemfilteran terlarang untuk mengetahui informasi
selengkapnya.
Aturan segmen tanggal inti:
Anda dapat menggunakan kolom tanggal inti dalam klausa
WHERE
tanpa menyertakannya dalam klausaSELECT
. Anda juga dapat menyertakan kolom dalam kedua klausa jika ingin.Contoh kueri ini menampilkan metrik
clicks
berdasarkan nama kampanye selama rentang tanggal. Perhatikan bahwasegments.date
tidak disertakan dalam klausulSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Jika Anda menyertakan kolom tanggal inti dalam klausa
SELECT
, Anda harus menentukan tanggal atau rentang tanggal yang terbatas dalam klausaWHERE
. Kolom yang ditentukan dalam klausaSELECT
danWHERE
tidak harus cocok.Contoh kueri ini menampilkan metrik
clicks
berdasarkan nama kampanye yang disegmentasikan menurut bulan untuk semua hari dalam rentang tanggal.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Tanggal ISO 8601
Anda dapat menggunakan format YYYY-MM-DD
(ISO 8601) untuk menentukan tanggal dan rentang tanggal,
misalnya:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
Untuk segmen tanggal inti yang memerlukan jangka waktu (segments.week
,
segments.month
, segments.quarter
), Anda dapat menggunakan operator =
dengan
hari pertama jangka waktu tersebut, misalnya:
WHERE segments.month = '2022-06-01'
Tanggal yang telah ditentukan sebelumnya
Anda juga dapat menggunakan tanggal dan rentang tanggal standar berikut:
Tanggal yang telah ditentukan sebelumnya | |
---|---|
TODAY |
Khusus hari ini. |
YESTERDAY |
Hanya kemarin. |
LAST_7_DAYS |
7 hari sebelumnya tidak termasuk hari ini. |
LAST_BUSINESS_WEEK |
Minggu kerja 5 hari sebelumnya (Senin sampai Jumat). |
THIS_MONTH |
Semua hari pada bulan ini. |
LAST_MONTH |
Semua hari pada bulan sebelumnya. |
LAST_14_DAYS |
14 hari sebelumnya tidak termasuk hari ini. |
LAST_30_DAYS |
30 hari sebelumnya tidak termasuk hari ini. |
THIS_WEEK_SUN_TODAY |
Periode antara Minggu sebelumnya dan hari ini. |
THIS_WEEK_MON_TODAY |
Periode antara Senin sebelumnya dan hari ini. |
LAST_WEEK_SUN_SAT |
Periode 7 hari mulai dari hari Minggu sebelumnya. |
LAST_WEEK_MON_SUN |
Periode 7 hari mulai dari hari Senin sebelumnya. |
Contoh:
WHERE segments.date DURING LAST_30_DAYS
Nol metrik
Saat menjalankan kueri, Anda mungkin menemukan metrik dengan nilai nol untuk beberapa entity. Pelajari cara menangani metrik nol dalam kueri.
Jenis enum TIDAK DIKETAHUI
Jika resource ditampilkan dengan jenis data enum UNKNOWN
, ini berarti
jenis tersebut tidak sepenuhnya didukung dalam versi API. Resource ini mungkin
telah dibuat melalui antarmuka lain. Misalnya, kampanye atau iklan baru diperkenalkan di UI Search Ads 360, tetapi belum didukung di versi API yang Anda minta.
Anda tetap dapat memilih metrik jika resource memiliki jenis UNKNOWN
, tetapi Anda harus memperhatikan hal berikut:
- Resource dengan jenis
UNKNOWN
mungkin didukung nanti, tetapi resource tersebut bisa tetapUNKNOWN
tanpa batas. - Objek baru dengan jenis
UNKNOWN
dapat muncul kapan saja. Objek ini kompatibel dengan versi sebelumnya karena nilai enum sudah tersedia. Kami memperkenalkan referensi pada perubahan ini karena tersedia agar Anda memiliki tampilan akun yang akurat. ResourceUNKNOWN
dapat muncul karena aktivitas baru di akun Anda melalui antarmuka lain atau karena resource tidak lagi didukung secara formal. - Resource
UNKNOWN
mungkin memiliki metrik mendetail yang dilampirkan pada resource tersebut, yang dapat Anda kuerikan. - Resource
UNKNOWN
biasanya terlihat sepenuhnya di UI Search Ads 360.