Batas dan kuota Data API

Batas dan kuota berikut berlaku untuk Data API.

Cara penerapan kuota

Semua permintaan ke Google Analytics Data API v1 memerlukan project Google Cloud dan tunduk pada kuota yang diuraikan di halaman ini. Kuota digunakan terlepas dari metode yang digunakan untuk mengidentifikasi project panggilan, termasuk:

• Permintaan yang diautentikasi dengan kredensial OAuth 2.0.
• Permintaan yang diautentikasi hanya menggunakan kunci API.

Kunci API digunakan untuk mengaitkan permintaan dengan project Google Cloud tertentu untuk tujuan kuota dan penagihan. Semua panggilan API yang dilakukan menggunakan kredensial atau kunci API dari project Anda akan dihitung berdasarkan kuota yang berlaku untuk project dan properti Google Analytics.

Kategori kuota

Data API memiliki empat kategori kuota permintaan: Core, Realtime, Funnel, dan Chat.

Permintaan API ke metode Core menagih kuota Core. Permintaan API ke metode Realtime menagih kuota Realtime. Permintaan API ke metode Funnel menagih kuota Funnel. Permintaan API ke metode Chat menagih kuota Chat. Setiap permintaan hanya menggunakan satu jenis kuota.

Kuota properti Analytics

Semua permintaan menggunakan kuota properti.

• Permintaan serentak diukur berdasarkan jumlah permintaan yang dieksekusi secara bersamaan. Untuk mengurangi konkurensi permintaan, tunggu hingga permintaan sebelumnya selesai sebelum mengirimkan permintaan tambahan.
• Error Server adalah kode 500 dan 503. Kuota Error Server hanya dikenai biaya jika permintaan menghasilkan error server. Jika kuota Error Server habis untuk pasangan project dan properti, semua permintaan ke properti dari project akan diblokir. Untuk mengetahui daftar lengkap respons error, lihat Respons Error.
• Setiap permintaan menggunakan kuota untuk Token Per Properti Per Jam dan Token Per Project Per Properti Per Jam. Artinya, satu properti harus diakses oleh lebih dari 3 project sebelum kuota "Tokens Per Property Per Hour" dapat habis sebelum kuota "Tokens Per Project Per Property Per Hour".

Properti diizinkan memiliki 120 permintaan yang berpotensi mencapai nilai minimum per jam. Dimensi userAgeBracket, userGender, brandingInterest, audienceId, dan audienceName berpotensi dikenai nilai minimum. Volume minimum data diterapkan agar siapa pun yang melihat laporan tidak dapat menyimpulkan demografi atau minat setiap pengguna.

Kuota token properti

Token digunakan dengan setiap permintaan ke Google Analytics Data API v1. Jumlah token yang dikenai biaya bergantung pada kompleksitas permintaan. Meskipun sebagian besar permintaan akan dikenai biaya 10 token atau kurang, permintaan yang lebih kompleks (seperti kueri Ask Advisor chat) akan menggunakan lebih banyak token.

Faktor yang memengaruhi konsumsi token

Biaya token yang tepat untuk sebuah permintaan ditentukan pada saat eksekusi, sehingga sulit untuk melakukan pra-penghitungan yang akurat. Biaya dipengaruhi oleh kombinasi faktor yang terkait dengan permintaan itu sendiri dan data pokok di properti Google Analytics. Faktor-faktor berikut dapat menyebabkan biaya yang lebih tinggi:

• Jumlah baris: Meminta jumlah baris yang lebih besar.
• Jumlah dimensi dan metrik: Menyertakan lebih banyak dimensi dan metrik.
• Kompleksitas filter: Menggunakan ekspresi filter yang kompleks.
• Panjang rentang tanggal: Membuat kueri selama periode tanggal yang lebih lama.
• Kardinalitas data: Dimensi dengan kardinalitas tinggi (banyak nilai unik, seperti pagePath, dimensi kustom) dapat meningkatkan biaya token secara signifikan.
• Volume peristiwa properti: Kueri pada properti dengan volume peristiwa yang lebih tinggi dapat menggunakan lebih banyak token daripada kueri yang sama pada properti dengan data yang lebih sedikit.

Memantau penggunaan token

Cara paling efektif untuk menentukan biaya token untuk panggilan API tertentu adalah dengan menyertakan parameter "returnPropertyQuota": true dalam isi permintaan (didukung di runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport, dan runFunnelReport). Respons API kemudian akan menyertakan objek PropertyQuota, yang menjelaskan token yang digunakan oleh permintaan tertentu tersebut dan saldo kuota yang tersisa.

Contoh permintaan dengan returnPropertyQuota

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

Contoh payload respons propertyQuota

Jika "returnPropertyQuota": true disetel, respons akan menyertakan objek propertyQuota dengan setiap kolom berisi QuotaStatus dengan bilangan bulat consumed dan remaining:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

Setiap kolom di propertyQuota sesuai dengan kuota di kuota properti Analytics. Biaya token satu permintaan API dipotong secara bersamaan dari tokensPerDay, tokensPerHour, dan tokensPerProjectPerHour. Jika ada bucket kuota yang mencapai 0 yang tersisa, permintaan berikutnya ke properti tersebut akan menampilkan error 429 RESOURCE_EXHAUSTED.

Praktik terbaik untuk menghindari error 429 RESOURCE_EXHAUSTED

• Pantau saldo remaining secara dinamis: Periksa propertyQuota.tokensPerProjectPerHour.remaining dan propertyQuota.tokensPerHour.remaining dalam respons dan batasi atau jeda tugas latar belakang yang tidak mendesak saat token yang tersisa berada di bawah nilai minimum keamanan.
• Batch kueri terkait: Gunakan batchRunReports atau batchRunPivotReports untuk mengelompokkan hingga 5 laporan dalam satu panggilan HTTP dan mengurangi overhead round-trip HTTP (perhatikan bahwa setiap laporan dalam batch tetap dihitung satu per satu terhadap kuota token dan concurrentRequests).
• Kurangi kompleksitas dan kardinalitas kueri: Batasi permintaan hanya untuk dimensi dan metrik yang Anda perlukan, persingkat dateRanges jika memungkinkan, dan hindari menggabungkan beberapa dimensi berkardinalitas tinggi (seperti pagePath atau fullPageUrl) dalam kueri polling yang sering.
• Kontrol konkurensi permintaan: Antrekan permintaan atau batasi ukuran worker pool agar permintaan yang sedang diproses tetap berada di bawah batas concurrentRequests (10 untuk Standard, 50 untuk Analytics 360).
• Terapkan backoff eksponensial dengan batas percobaan ulang: Jika permintaan gagal dengan 429 RESOURCE_EXHAUSTED, 500 INTERNAL, atau 503 UNAVAILABLE, coba lagi menggunakan backoff eksponensial yang dipangkas seperti yang dijelaskan dalam Respons error.

Pemantauan dan konsumsi token chat

Untuk permintaan chat Ask Advisor, token mewakili komputasi model, penalaran, dan biaya pengambilan data yang mendasarinya. Pemakaian token chat dipengaruhi oleh:

• Cakupan kueri dan analisis: Kompleksitas dan luasnya analisis yang diminta.
• Token input dan output model: Volume data kontekstual yang diproses dan narasi respons yang dihasilkan.
• Token penalaran: Langkah-langkah penalaran model yang diperlukan untuk menyintesis temuan.
• Latensi eksekusi: Waktu pemrosesan yang diperlukan untuk eksplorasi data multi-langkah.

Untuk memantau penggunaan token chat, tetapkan "returnPropertyQuota": true di ChatRequest. Respons akan menyertakan objek PropertyChatQuota yang berisi kolom tokensPerDay dan tokensPerHour dengan saldo yang digunakan dan tersisa.