Membuat laporan penelusuran di Search Ads 360 Reporting API

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

Catatan: Bahasa Kueri Search Ads 360 memberikan informasi mendetail tentang cara menggunakan setiap klausa kueri penelusuran.

Buat permintaan

Untuk memberikan permintaan, Anda harus meneruskan string customer_id dan query ke antarmuka SearchAds360Service.SearchStream atau SearchAds360Service.Search.

Catatan: Contoh di bawah ini menampilkan permintaan HTTP/JSON yang mendasarinya. Ini digunakan untuk menunjukkan konsep. Sebaiknya gunakan library klien yang didasarkan pada gRPC untuk mengirim permintaan di aplikasi Anda sendiri.

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, resource campaign adalah resource atribusi dari resource ad_group. Artinya, Anda dapat menyertakan kolom seperti campaign.id dan campaign.bidding_strategy_type dalam kueri saat menggunakan ad_group di klausa FROM.

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 klausa SELECT 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 klausa FROM, 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 klausa SELECT 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 klausa FROM, gunakan menu dropdown Ya/Tidak untuk memfilter metrik yang tidak tersedia.

Catatan: Saat mendapatkan metrik terkait mata uang (misalnya, cost_micros) untuk tanggal atau rentang tanggal tertentu, pastikan untuk menyertakan segments.date dalam klausa SELECT.

Mengelompokkan resource

Beberapa resource memiliki kolom resource segmentasi yang dapat Anda pilih saat resource berada dalam klausa FROM. Misalnya, jika Anda memilih kolom resource campaign, seperti campaign.name, saat menggunakan campaign_budget dalam klausa FROM, campaign.resource_name akan otomatis ditampilkan dan disegmentasikan, karena campaign adalah resource segmentasi dari campaign_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 kolom segments yang mencantumkan semua kolom resource yang kompatibel, kolom metrics, dan kolom segments lainnya yang dapat Anda sertakan dalam klausa SELECT.

Catatan: Lihat Bahasa Kueri Search Ads 360 untuk mempelajari cara menggunakan setiap klausa kueri.

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

Perhatian: Jumlah baris dapat meningkat secara eksponensial untuk setiap kolom segments tambahan yang Anda tambahkan ke kueri.

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

Catatan: Kolom resource_name resource dalam klausa FROM selalu ditampilkan, meskipun tidak ditentukan dalam klausa SELECT. Lihat kolom resource_name untuk mengetahui informasi selengkapnya.

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 klausa SELECT. Anda juga dapat menyertakan kolom dalam kedua klausa jika ingin.

  Contoh kueri ini menampilkan metrik clicks berdasarkan nama kampanye selama rentang tanggal. Perhatikan bahwa segments.date tidak disertakan dalam klausul SELECT.

  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 klausa WHERE. Kolom yang ditentukan dalam klausa SELECT dan WHERE 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'

Catatan: Jika menentukan tanggal yang bukan hari pertama menstruasi, Anda akan menerima error MISALIGNED_DATE_FOR_FILTER.

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 tetap UNKNOWN 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. Resource UNKNOWN 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.