Mengelola kuota untuk Google Analytics Data API

Minhaz Kazi, Developer Advocate, Google Analytics – February 2023

Jika Anda mengembangkan aplikasi menggunakan Google Analytics Data API, Anda harus memahami cara kerja kuota dan batas untuk API. Jika aplikasi Anda didesain dengan baik, pengguna cenderung tidak akan mencapai batas kuota. Beberapa praktik terbaik yang relevan juga menghasilkan kueri berperforma baik untuk API. Hal ini dapat mempercepat laporan dan dasbor di aplikasi Anda serta menghasilkan pengalaman pengguna yang lebih diinginkan. Artikel ini membahas sistem kuota dan praktik terbaik untuk menerapkan Google Analytics Data API.

Memahami sistem kuota untuk Google Analytics Data API

Karena Google Analytics digunakan oleh jutaan developer dan pengguna, kuota pada permintaan API melindungi sistem agar tidak memproses data lebih banyak daripada yang dapat ditanganinya sekaligus memastikan distribusi resource sistem yang merata. Data API untuk properti Google Analytics 4 menggunakan sistem token bucket untuk mengelola kuota API. Untuk memahami konsepnya: bayangkan ada bucket yang dapat menampung jumlah token maksimum. Setiap permintaan API akan memeriksa bucket terlebih dahulu. Jika token sudah habis, permintaan akan gagal. Jika masih ada, permintaan akan dieksekusi dan akan memakai satu atau beberapa token dari bucket, bergantung pada kompleksitas permintaan. Token akan diisi kembali ke dalam bucket hingga jumlah maksimum dengan interval waktu yang tetap.

Bergantung pada metode Data API yang Anda gunakan, ada tiga kategori kuota yang terpisah:

• Real-Time (untuk runRealtimeReport)
• Funnel (untuk runFunnelReport)
• Core (untuk semua metode lainnya)

Dan metode Data API akan memeriksa token kuota di beberapa bucket:

1. Per property per day
2. Per property per hour
3. Per project per property per hour
4. Concurrent requests per property
5. Server errors per project per property per hour

Kelima bucket ini diperiksa setiap kali permintaan Data API masuk untuk properti. Jika salah satu bucket kosong, permintaan akan langsung gagal dengan error 429. Jika tidak ada bucket yang tidak kosong, satu token akan dipakai dari bucket Concurrent requests per property, lalu permintaan API akan dieksekusi. Berdasarkan kompleksitas permintaan, sejumlah token tertentu akan dipakai dari masing-masing tiga bucket pertama setelah eksekusi selesai. Concurrent requests per property juga akan diisi ulang token pada saat ini.

Kuota Per project per property per hour memastikan pengurangan kuota untuk satu atau beberapa pengguna tidak akan memengaruhi pengguna aplikasi Anda yang lain. Di sini, project mengacu pada project GCP di aplikasi Anda. Kuota Per property per hour biasanya berjumlah empat kali lipat kuota Per project per property per hour. Jadi untuk pengguna akhir, properti harus diakses oleh setidaknya empat project yang berbeda sebelum kuota Per property per hour dapat dihabiskan. Pemberlakuan kuota di level project dan properti memastikan bahwa masalah kuota dibatasi untuk satu properti dan tidak akan memengaruhi properti lain yang diakses oleh aplikasi Anda.

Peringatan: Developer sangat tidak dianjurkan untuk melakukan sharding token kuota di beberapa project API. Tindakan ini merupakan pelanggaran Persyaratan Layanan Google API.

Kuota Server errors mengacu pada respons API dengan kode 500 atau 503. Jika aplikasi Anda membuat terlalu banyak error saat mengakses properti, kuota Server errors per project per property per hour akan habis.

Semua token kuota akan kembali diisi hingga ke batasnya pada interval yang ditetapkan. Lihat Kuota Google Analytics Data API untuk informasi kuota terbaru. Misalnya, metode Core mendapatkan 1.250 token kuota di bucket Per project per property per hour. Dengan asumsi bahwa permintaan rata-rata dari aplikasi Anda memakai 10 token kuota, aplikasi Anda akan dapat membuat 125 permintaan Core per jam untuk properti standar dan 10x dari jumlah tersebut (1.250 permintaan Core) untuk setiap properti Analytics 360. Batas token kuota yang lebih tinggi adalah salah satu manfaat utama dari properti Analytics 360.

Karena pemakaian token untuk tiga bucket pertama bergantung pada kompleksitas permintaan, penggunaan token yang tepat akan sulit diprediksi sebelum permintaan dieksekusi. Hal berikut ini biasanya akan meningkatkan kompleksitas permintaan, sehingga menyebabkan penggunaan token:

• Meminta dimensi lebih banyak
• Membuat kueri untuk rentang waktu yang lebih tinggi
• Menyertakan dimensi dengan kardinalitas lebih tinggi
• Membuat kueri untuk properti dengan jumlah peristiwa yang lebih tinggi

Oleh karena itu, kueri yang sama untuk dua properti berbeda dapat menyebabkan penggunaan token yang sama sekali berbeda karena kardinalitas dimensi dapat bervariasi atau volume traffic mungkin berbeda. Namun, properti dengan tingkat traffic dan konfigurasi serupa dapat memiliki penggunaan token yang serupa. Anda dapat menggunakan asumsi ini untuk memprediksi penggunaan token pelanggan selama fase perencanaan dan desain aplikasi.

Catatan: Jika sebelumnya Anda menggunakan Reporting API untuk Universal Analytics, Anda akan melihat bahwa Reporting API menerapkan kuota pada level project API/Aplikasi. Namun, untuk Data API, penerapannya terjadi pada level properti Google Analytics serta pada level project API.

Memantau penggunaan kuota

Untuk memantau penggunaan kuota dan menyampaikan informasi tersebut kepada pengguna akhir, Anda dapat menambahkan "returnPropertyQuota": true ke isi permintaan API. Tindakan ini akan menampilkan objek PropertyQuota beserta respons API. Objek PropertyQuota akan berisi jumlah pemakaian dan status kuota yang tersisa untuk kelima bucket. Berikut adalah contoh isi dan respons permintaan:

Permintaan

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Respons

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Dengan demikian, setelah setiap permintaan Data API yang berhasil, Anda akan melihat jumlah kuota yang dipakai dan jumlah kuota yang tersisa untuk properti tersebut. Anda juga dapat menampilkan informasi ini kepada pengguna melalui antarmuka aplikasi.

Catatan: Pada tahap Data API saat ini, Anda harus berhasil mengeksekusi permintaan API untuk mendapatkan kembali objek PropertyQuota. Jika properti telah menghabiskan bucket token kuota, permintaan Anda akan gagal dengan error 429 dan respons tidak akan berisi objek PropertyQuota. Jika Anda terkena dampak hal ini dan merasa aplikasi Anda akan diuntungkan jika memiliki cara yang terpisah untuk mengakses informasi kuota, beri +1 ke permintaan fitur ini di issue tracker.

Pengelolaan kuota

Sebaiknya terapkan praktik terbaik pengelolaan kuota yang dijelaskan di bawah ini untuk mendapatkan hasil maksimal dari Data API. Selain itu, mengupgrade properti ke 360 dapat meningkatkan jumlah data yang diakses melalui API.

Praktik terbaik

Ada dua cara untuk mengurangi penggunaan kuota aplikasi Anda:

• Mengirim lebih sedikit permintaan API
• Mengirim permintaan API yang tidak terlalu kompleks

Dengan mengingat dua prinsip ini, berikut adalah praktik yang dapat Anda terapkan:

• Menyimpan ke cache: Menerapkan lapisan cache akan bermanfaat bagi pengelolaan kuota dan kegunaan untuk aplikasi Anda. Google Analytics akan menyimpan permintaan API Anda dalam cache, tetapi permintaan berulang akan tetap dikenai token kuota. Dengan menyimpan respons API ke dalam cache, Anda dapat mengurangi jumlah permintaan berulang secara signifikan. Misalnya, data intrahari untuk properti standar dapat memiliki waktu habis masa berlaku untuk cache sebesar 4 jam atau lebih. Lihat Keaktualan data untuk Google Analytics.
• Menggabungkan permintaan: Coba gabungkan beberapa permintaan API menjadi satu permintaan. Misalnya, 5 permintaan data dalam jangka waktu 2 hari dapat menggunakan 3 kali lipat token kuota dibandingkan dengan 1 permintaan untuk jangka waktu 10 hari. Jika Anda memiliki beberapa permintaan yang hanya bervariasi berdasarkan satu dimensi, sebaiknya digabungkan menjadi satu permintaan.
• Menyederhanakan permintaan: Batasi permintaan Anda ke jumlah minimum data yang diperlukan oleh aplikasi Anda dan pengguna. Sejumlah besar baris/kolom atau kriteria filter yang kompleks akan memakai lebih banyak token kuota. Rentang tanggal yang lebih lama biasanya lebih mahal (misalnya, perubahan rentang tanggal dari 28 hari menjadi 365 hari dapat memakai 3 kali lipat token kuota). Anda juga dapat mempertimbangkan penggunaan dimensi dengan kardinalitas lebih rendah jika memungkinkan (misalnya, meminta dateHour, bukan dateHourMinute).
• Penggunaan limit yang efektif: Mengubah limit dalam permintaan API untuk mengurangi jumlah baris yang ditampilkan tidak akan memengaruhi token kuota yang dipakai secara signifikan. Misalnya, 5 permintaan dengan batas 10 ribu baris dapat memakai token kuota lima kali lipat dibandingkan 1 permintaan dengan batas 50 ribu.
• Menggunakan kategori metode yang tepat: Seperti yang disebutkan di atas, batas kuota tersebar di ketiga kategori metode. Penggunaan metode yang tepat untuk kasus penggunaan yang tepat dapat menghemat kuota pada kategori lain. Misalnya, daripada membuat funnel Anda sendiri di aplikasi menggunakan data dari metode Core, gunakan metode runFunnelReport untuk membuat funnel.
• Memperbarui setelan default: Saat membuat atau menyesuaikan laporan di platform, pengguna mungkin tidak memperbarui opsi default yang ditampilkan oleh aplikasi dan hanya mengubahnya saat runtime. Jika aplikasi Anda memiliki rentang tanggal default 365 hari dan pengguna biasanya melihat laporan 28 hari, setelan ini pada akhirnya akan memakai lebih banyak kuota dari yang diperlukan secara berkala. Pertimbangkan untuk membatasi rentang dan pilihan di setelan default dan izinkan pengguna memilih setelan optimal untuk kasus penggunaan mereka. Atau dalam beberapa kasus, Anda juga dapat membatasi setelan default yang dapat diubah pengguna.
• Permintaan antrean dan pemuatan lambat: Perhatikan batas token Concurrent Requests Per Property. Aplikasi Anda tidak boleh mengirimkan terlalu banyak permintaan secara bersamaan. Jika aplikasi Anda memiliki banyak elemen UI yang menghasilkan jumlah permintaan API yang signifikan, pertimbangkan untuk menggunakan penomoran halaman UI, pemuatan lambat, dan fitur antrean permintaan dengan backoff eksponensial untuk percobaan ulang. Gunakan metode returnPropertyQuota untuk secara agresif memantau penggunaan token Concurrent Requests Per Property di aplikasi Anda.

Mengelola Pengalaman dan Ekspektasi Pengguna

• Berikan masukan kepada pengguna sebelum mereka menjalankan kueri dengan potensi penggunaan token yang tinggi. Misalnya, kueri dengan beberapa dimensi berkardinalitas tinggi atau dengan jangka waktu yang panjang dapat menggunakan token dalam jumlah besar. Memberikan peringatan dan perintah konfirmasi untuk kueri semacam itu dapat mencegah pengguna membuat perubahan yang tidak perlu pada laporan dan membantu mereka membatasi cakupan pada kueri mereka.
• Untuk solusi pelaporan yang disesuaikan, sediakan cara bagi pengguna untuk memahami penggunaan kueri di setiap elemen dalam laporan. Misalnya, Anda dapat menyediakan tampilan debug yang mencantumkan penggunaan token kuota untuk setiap elemen laporan.
• Berikan masukan tentang jenis error kuota tertentu dan tentukan tindakan pengguna.
• Karena properti Google Analytics 360 mendapatkan batas kuota 5-10x kali lipat dibandingkan dengan properti standar, Anda mendapatkan fleksibilitas yang lebih besar dengan properti Google Analytics 360.

Penambahan kuota API di atas batas default tidak tersedia untuk Data API untuk Google Analytics 4. Google Analytics 360 menyediakan batas kuota yang lebih tinggi untuk properti Google Analytics 4. Jika pengguna Anda mencapai batas kuota bahkan setelah menerapkan praktik terbaik, mereka harus mempertimbangkan untuk mengupgrade properti ke 360. Opsi lain bagi pengguna tersebut adalah menggunakan BigQuery Export Google Analytics. Dengan demikian, pengguna dapat mengekspor data tingkat peristiwa ke BigQuery dan menjalankan analisis mereka sendiri.

Untuk pertanyaan lebih lanjut terkait kuota Data API, buka GA Discord atau ajukan pertanyaan di Stack Overflow. Jika Anda memiliki permintaan fitur khusus seputar Data API, Anda dapat mempostingnya di Issue Tracker kami.