Search Ads 360 Reporting API versi baru kini tersedia. Bergabunglah dengan grup Google searchads-api-announcements untuk terus mendapatkan informasi terbaru tentang peningkatan dan rilis mendatang.

Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat laporan penelusuran di Search Ads 360 Reporting API

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, resource campaign adalah resource yang diatribusikan dari resource ad_group. Ini berarti Anda bisa sertakan kolom seperti campaign.id dan campaign.bidding_strategy_type di kueri saat menggunakan ad_group dalam klausa FROM.

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 klausa SELECT 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 klausa FROM, 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 klausa SELECT 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 klausa FROM, 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 resource campaign, seperti campaign.name, jika menggunakan campaign_budget dalam klausa FROM, campaign.resource_name akan secara otomatis ditampilkan dan disegmentasikan, karena campaign adalah menyegmentasi resource campaign_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 kolom segments yang mencantumkan semua kolom resource, kolom metrics, dan kolom segments lainnya yang kompatibel kolom yang dapat Anda sertakan dalam klausa SELECT.

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 Klausa SELECT. 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 bahwa segments.date tidak disertakan dalam klausa SELECT.
```
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 klausa WHERE Anda. Kolom yang ditentukan dalam Klausa SELECT dan WHERE 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 ada UNKNOWN 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. Resource UNKNOWN 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.