Data Laporan Kueri

Metode reportData.query menyediakan cara sinkron untuk mengambil data laporan. Tidak seperti layanan Reports standar, yang menghasilkan laporan berbasis file (CSV atau Excel), metode ini menampilkan data JSON terstruktur langsung dalam respons. Metode ini menghilangkan kebutuhan untuk menentukan, membuat, dan menyimpan resource Report terlebih dahulu, sehingga ideal untuk pengambilan dan eksplorasi data real-time.

Ringkasan

Ikuti panduan ini untuk mempelajari cara menggunakan endpoint ini untuk membuat kueri data pelaporan Campaign Manager 360.

Menyiapkan permintaan

Buat ReportDataQueryRequest yang menentukan dimensi, metrik, rentang tanggal, filter, dan kriteria pengurutan.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Objek DateRange yang menentukan jangka waktu untuk kueri. Jangka waktu ini dapat berupa rentang tanggal kustom atau rentang tanggal relatif.
dimensionNames
Daftar nama dimensi standar untuk dikelompokkan.
metricNames
Wajib. Daftar nama metrik standar yang akan disertakan.
dimensionFilters
Daftar objek DimensionValue yang digunakan untuk memfilter data laporan. Gunakan parameter ini untuk membatasi hasil kueri ke nilai dimensi tertentu.
sortBys
Konfigurasi pengurutan untuk dimensi atau metrik. Setiap konfigurasi mencakup nama kolom dan urutan pengurutan.
maxResults
Jumlah maksimum baris yang akan ditampilkan per halaman (Default: 100, Maks: 1000).

Penomoran halaman

Kolom maxResults mengontrol jumlah hasil yang ditampilkan dalam satu respons. Misalnya, jika Anda menetapkan maxResults ke 10, API akan menampilkan maksimal 10 hasil. API mungkin menampilkan kurang dari 10 hasil jika ada kurang dari 10 hasil yang cocok dengan permintaan Anda.

Jika hasil tambahan tersedia, respons akan menyertakan nextPageToken. Untuk mengambil halaman hasil berikutnya, kirim permintaan yang sama lagi dengan kolom pageToken yang ditetapkan ke token ini. Pertahankan semua parameter permintaan lainnya.

Mengirim permintaan

Kirim permintaan POST HTTP ke reportdata/query endpoint:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

Pastikan permintaan Anda diautentikasi dengan kredensial OAuth 2.0 standar dan cakupan yang diperlukan. Lihat Mengotorisasi Permintaan untuk mengetahui informasi selengkapnya.

Respons yang berhasil

Kueri yang berhasil akan menampilkan respons 200 OK HTTP dengan payload JSON yang berisi columnHeaders, rows, dan totalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
Nama dan jenis (DIMENSION atau METRIC) kolom yang ditampilkan.
rows
Daftar objek ReportDataRow yang berisi hasil kueri. Nilai string di setiap baris sejajar berdasarkan posisi dengan columnHeaders.
totalRow
Satu baris agregat yang mewakili jumlah semua metrik yang cocok. Kolom dimensi dan metrik yang tidak dapat dijumlahkan (misalnya, metrik Jangkauan seperti uniqueReachTotalReach) kosong ("") di baris ini.
nextPageToken
Token yang digunakan dalam permintaan berikutnya untuk mengambil halaman berikutnya jika ada baris tambahan.

Latensi dan waktu tunggu

Karena ini adalah endpoint sinkron, kueri akan langsung dijalankan dan data akan ditampilkan langsung dalam respons (hingga batas penomoran halaman maxResults). Kueri memiliki waktu eksekusi maksimum 60 detik. Jika kueri melebihi batas ini, API akan menghentikan operasi dan menampilkan error HTTP 503 Service Unavailable.

Jika Anda mengalami error ini, coba persempit rentang tanggal, persempit filter (seperti memfilter menurut pengiklan atau kampanye tertentu), atau kurangi jumlah dimensi dan metrik yang diminta. Atau, jalankan Report menggunakan reports.run untuk membuat file laporan yang dapat didownload secara asinkron.

Batas dan batasan kueri

Endpoint reportdata.query menerapkan beberapa batasan untuk memastikan respons yang andal. Permintaan yang melanggar batasan ini akan ditolak dengan respons HTTP 400 Bad Request.

Batas rentang tanggal

  • Untuk rentang tanggal kustom, startDate harus berada dalam periode ketersediaan data untuk jenis data laporan yang diminta. Untuk mengetahui detailnya, lihat Ketersediaan data.

Batasan metrik dan dimensi

  • Setidaknya satu metrik harus diberikan di metricNames.
  • Metrik dan dimensi dalam daftar metricNames dan dimensionNames harus unik.
  • Metrik dan dimensi yang diberi label Hanya download tidak dapat digunakan dalam kueri ini.

Batas kuota

Permintaan ke endpoint ini menggunakan kuota berikut:

  • Batas frekuensi pengguna: 120 permintaan per menit per pengguna (2 QPS)
  • Batas harian per project: 10.000 permintaan per hari per project

Permintaan yang melebihi batas ini akan gagal dengan error HTTP 429 Too Many Requests. Jika Anda menelusuri hasil, setiap permintaan untuk halaman baru (menggunakan parameter pageToken) akan dihitung sebagai kueri terpisah dan menggunakan kuota ini.