Baca bagian di bawah untuk mempelajari cara membuat laporan penelusuran di Iklan Penelusuran 360 Reporting API.
Layanan penelusuran
Search Ads 360 Reporting API menyediakan layanan khusus untuk penelusuran dan pelaporan.
SearchAds360Service
adalah layanan pelaporan dan pengambilan objek terpadu
yang menyediakan dua metode penelusuran: SearchStream
dan Search
. Penelusuran
diteruskan string kueri yang ditulis dalam Bahasa Kueri Search Ads 360. Anda dapat menentukan kueri untuk:
- Mengambil atribut objek tertentu.
- Mengambil metrik performa untuk objek berdasarkan rentang tanggal.
- Mengurutkan objek berdasarkan atributnya.
- Filter hasil 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, ketika Anda
mengambil campaign.id
, campaign.name
, dan metrics.clicks
, API akan menampilkan
SearchAds360Row
berisi objek kampanye dengan kolom id
dan name
dan objek metrics
dengan kolom clicks
yang disetel.
Metode penelusuran
SearchStream
Mengirim satu permintaan dan memulai koneksi persisten dengan Search Ads 360 Reporting API, berapa pun ukuran laporannya.
- Paket data langsung mulai didownload dengan seluruh hasil yang di-cache di buffer data.
- Kode Anda dapat mulai membaca data yang di-buffer tanpa harus menunggu untuk menyelesaikan streaming.
Search
Mengirim beberapa permintaan yang dipaginasi untuk mendownload seluruh laporan.
SearchStream
biasanya menawarkan performa yang lebih baik karena menghilangkan
waktu jaringan bolak-balik yang diperlukan untuk meminta halaman individual. Sebaiknya gunakan
SearchStream
untuk semua laporan yang berjumlah lebih dari 10.000 baris. Tidak ada
perbedaan performa antarmetode untuk laporan yang lebih kecil (<10.000 baris).
Metode yang Anda gunakan tidak memengaruhi kuota dan batas API: satu kueri atau laporan dihitung sebagai satu operasi terlepas dari apakah hasilnya di-page atau di-streaming.
Contoh kueri penelusuran
Contoh kueri ini menampilkan data performa untuk akun selama 30 hari terakhir menurut kampanye, 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 mengajukan permintaan, Anda harus meneruskan string customer_id
dan query
ke SearchAds360Service.SearchStream
atau SearchAds360Service.Search
dalam antarmuka berbasis web
yang sederhana.
Permintaan terdiri atas POST
HTTP ke Search Ads 360 Reporting API
server 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 disertakan 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 kumpulan atribut yang diisi berdasarkan kolom yang diminta
dalam klausa SELECT
kueri. Atribut yang tidak disertakan dalam SELECT
tidak diisi dalam objek dalam respons.
Misalnya, kueri di bawah ini mengisi setiap objek SearchAds360Row
hanya 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 Referensi
mencakup 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
menampilkan daftar semua kolom metrik dan segmen yang tersedia.
Beberapa resource, segmen, dan metrik tidak kompatibel dan tidak dapat digunakan bersama-sama, sementara yang lain sepenuhnya kompatibel dan saling memuji. Masing-masing halaman resource mencakup informasi berikut (jika tersedia dan sesuai) dan lain-lain:
- Resource yang diatribusikan
Untuk beberapa resource, Anda mungkin memiliki opsi untuk secara implisit bergabung ke resource sumber daya dengan memilih {i>field<i} mereka bersama dengan {i>field<i} sumber daya yang ada di klausul
FROM
. Misalnya, resourcecampaign
adalah resource yang diatribusikan dari resourcead_group
. Ini berarti Anda bisa sertakan kolom seperticampaign.id
dancampaign.bidding_strategy_type
di kueri saat menggunakanad_group
dalam klausaFROM
.Bagian Resource yang diatribusikan mencantumkan resource yang diatribusikan yang tersedia. Bukan semua resource memiliki resource yang diatribusikan.
- Kolom kolom resource
Semua kolom resource disertakan di kolom Kolom resource. Setiap kolom referensi terhubung ke detail selengkapnya tentang kolom tersebut, termasuk deskripsi, kategori, tipe data, jenis data, URL, dan dapat difilter, dapat dipilih, dapat diurutkan, dan pengaturan berulang.
- Kolom segmen
Tidak semua kolom segmen dapat dipilih menggunakan resource tertentu.
Kolom Segmen mencantumkan kolom
segments
yang dapat Anda gunakan di klausaSELECT
yang sama dengan kolom resource. Setiap kolom tertaut ke kolom detail tentang {i>field<i}, termasuk deskripsi, kategori, tipe data, jenis URL, serta setelan yang dapat difilter, dapat dipilih, dapat diurutkan, dan berulang. Jika Anda dengan menggunakan resource dalam klausaFROM
, Anda dapat menggunakan menu dropdown Ya/Tidak untuk memfilter segmen yang tidak tersedia.- Kolom metrik
Tidak semua kolom metrik dapat dipilih dengan resource tertentu.
Kolom Metrik mencantumkan kolom
metrics
yang dapat Anda gunakan di klausaSELECT
yang sama dengan kolom resource. Setiap kolom tertaut ke kolom detail tentang {i>field<i}, termasuk deskripsi, kategori, tipe data, jenis URL, serta setelan yang dapat difilter, dapat dipilih, dapat diurutkan, dan berulang. Jika Anda menggunakan resource dalam klausaFROM
, gunakan menu dropdown Ya/Tidak untuk memfilter metrik yang tidak tersedia.
- Mengelompokkan sumber daya
Beberapa resource memiliki kolom resource segmentasi yang dapat Anda pilih saat resource ada dalam klausa
FROM
Anda. Misalnya, jika Anda memilih kolom resourcecampaign
, seperticampaign.name
, jika menggunakancampaign_budget
dalam klausaFROM
,campaign.resource_name
akan secara otomatis ditampilkan dan disegmentasikan, karenacampaign
adalah menyegmentasi resourcecampaign_budget
.Bagian Menyegmentasikan resource mencantumkan resource segmentasi yang tersedia. Bukan semua sumber daya memiliki sumber daya segmentasi.
- Dapat dipilih dengan
Beberapa kolom
segments
tidak kompatibel dengan resource, segmen, dan metrik.Halaman
segments
menyertakan kolom Dapat dipilih dengan yang dapat diluaskan untuk setiap kolomsegments
yang mencantumkan semua kolom resource, kolommetrics
, dan kolomsegments
lainnya yang kompatibel kolom yang dapat Anda sertakan dalam klausaSELECT
.
Segmentasi
Anda dapat menyegmentasi hasil penelusuran dengan menambahkan
segments.FIELD_NAME
ke klausa SELECT
kueri Anda.
Misalnya, segments.device
di
di bawah, menghasilkan laporan dengan baris untuk masing-masing impressions
untuk resource yang ditentukan dalam klausa FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
Hasil yang ditampilkan oleh SearchAds360Service.SearchStream
terlihat seperti ini
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
daftar bidang segmen yang tersedia yang dapat Anda gunakan.
Beberapa segmen
Anda dapat menentukan beberapa segmen dalam klausa SELECT
dalam kueri Anda. Tujuan
berisi satu objek SearchAds360Row
untuk setiap kombinasi dari
instance resource utama yang ditentukan dalam klausa FROM
dan
value setiap kolom segment
yang dipilih.
Misalnya, kueri berikut akan mengembalikan satu baris untuk setiap kombinasi
campaign
, segments.ad_network_type
, dan segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Perhatikan, hasil secara implisit disegmentasikan berdasarkan setiap instance instance bukan dengan nilai masing-masing {i>field<i} 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 awalnya disegmentasikan berdasarkan resource yang ditentukan dalam FROM
. Metrik disegmentasikan menurut kolom resource_name
di resource ini
Contoh kueri ini otomatis menampilkan ad_group.resource_name
dan secara implisit
akan menggunakannya untuk menyegmentasikan metrik di tingkat ad_group
.
SELECT metrics.impressions
FROM ad_group
String JSON yang ditampilkan akan 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 tertentu.
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 untuk aturan umum yang
tidak dapat menggunakan bidang segmen dalam klausa WHERE
, kecuali jika Anda juga menyertakan
dalam klausa SELECT
. Lihat Pemfilteran terlarang untuk informasi selengkapnya
tidak akurat atau tidak sesuai.
Aturan segmen tanggal inti:
Anda dapat menggunakan kolom tanggal inti dalam klausa
WHERE
tanpa menyertakannya dalam KlausaSELECT
. Anda juga dapat menyertakan kolom tersebut dalam kedua klausa jika mau.Contoh kueri ini menampilkan metrik
clicks
menurut nama kampanye selama tanggal tersebut {i>range<i}. Perlu diketahui bahwasegments.date
tidak disertakan dalam klausaSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Jika menyertakan kolom tanggal inti dalam klausa
SELECT
, Anda harus menentukan tanggal atau rentang tanggal yang terbatas dalam klausaWHERE
Anda. Kolom yang ditentukan dalam KlausaSELECT
danWHERE
tidak harus cocok.Contoh kueri ini menampilkan
clicks
metrik menurut nama kampanye yang dikelompokkan 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
Anda juga dapat menggunakan tanggal dan rentang tanggal standar berikut:
Tanggal yang telah ditentukan | |
---|---|
TODAY |
Hanya 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 dalam bulan ini. |
LAST_MONTH |
Semua hari dalam sebulan sebelumnya. |
LAST_14_DAYS |
14 hari sebelumnya kecuali hari ini. |
LAST_30_DAYS |
30 hari sebelumnya kecuali hari ini. |
THIS_WEEK_SUN_TODAY |
Periode antara hari 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 yang dimulai dari hari Senin sebelumnya. |
Contoh:
WHERE segments.date DURING LAST_30_DAYS
Tidak ada metrik
Saat mengeksekusi kueri, Anda mungkin menemukan metrik dengan nilai nol untuk beberapa entitas. Pelajari cara menangani metrik dengan jumlah nol di kueri Anda.
Jenis enum TIDAK DIKETAHUI
Jika resource ditampilkan dengan jenis data enum UNKNOWN
, ini berarti
jenisnya tidak sepenuhnya didukung dalam versi API. Referensi ini mungkin memiliki
dibuat melalui antarmuka lain. Misalnya, kampanye atau iklan baru
diperkenalkan di UI Search Ads 360, tetapi belum didukung di versi API
yang Anda kueri.
Anda masih dapat memilih metrik jika resource memiliki jenis UNKNOWN
, tetapi
perlu memperhatikan hal berikut:
- Resource dengan jenis
UNKNOWN
mungkin didukung nanti, tetapi dapat tetap adaUNKNOWN
tanpa batas waktu. - Objek baru dengan jenis
UNKNOWN
dapat muncul kapan saja. Objek ini kompatibel dengan sistem lama karena nilai enum sudah tersedia. Kami memperkenalkan dengan perubahan ini saat tersedia sehingga Anda memiliki untuk akun Anda. ResourceUNKNOWN
dapat muncul karena aktivitas di akun Anda melalui antarmuka lain atau karena resource tidak lagi didukung secara formal. UNKNOWN
resource mungkin memiliki metrik mendetail yang terlampir dan dapat Anda kueri.- Resource
UNKNOWN
biasanya terlihat sepenuhnya di UI Search Ads 360.