Google Calendar API memiliki kuota untuk memastikan bahwa API tersebut digunakan secara adil oleh semua pengguna. Ada tiga batasan penting yang perlu dipertimbangkan saat menggunakan Calendar API:
Kuota penggunaan API: Diterapkan per project dan per pengguna. Untuk informasi selengkapnya, lihat Jenis kuota penggunaan Calendar API.
Batas penggunaan umum Google Kalender: Google Calendar API adalah layanan bersama yang memiliki batasan untuk melindungi performa keseluruhan sistem Google Workspace. Untuk mengetahui informasi selengkapnya, lihat Menghindari batas penggunaan Kalender
Batasan operasional: Batasan ini dapat dibatasi kapan saja. Misalnya, jika Anda mencoba menulis ke satu kalender secara berurutan dengan cepat.
Kuota Calendar API
Dua jenis kuota diterapkan:
Per menit per project: Ini adalah jumlah permintaan yang dapat dibuat project Google Cloud Anda dalam satu menit.
Per menit per pengguna per project: Ini adalah jumlah permintaan yang dapat dibuat oleh satu pengguna tertentu di project Cloud Anda. Batas ini bertujuan untuk membantu Anda memastikan distribusi penggunaan yang adil di antara pengguna Anda.
Kuota dihitung per menit menggunakan jendela geser. Lonjakan traffic yang cepat dan melebihi kuota per menit selama satu menit akan menyebabkan pembatasan laju selama periode berikutnya untuk memastikan bahwa, rata-rata, penggunaan Anda tetap berada dalam kuota.
Tabel berikut menjelaskan batas ini:
| Jenis batas penggunaan | Batas |
|---|---|
| Per menit per project | 10.000 permintaan |
| Per menit per pengguna per project | 600 permintaan |
Nilai minimum penagihan harian
Batas per hari per project ini menentukan jumlah maksimum permintaan yang dapat digunakan project Google Cloud Anda dalam jangka waktu 24 jam sebelum biaya berlaku.
Penggunaan di bawah batas ini tidak dikenai biaya tambahan dan akun Google Cloud Anda tidak ditagih. Detail penagihan lengkap akan dibagikan pada tahun 2026 dengan pemberitahuan setidaknya 90 hari sebelum perubahan apa pun berlaku.
Anda tidak dapat meminta peningkatan batas nilai minimum harian ini.
Tabel berikut menjelaskan batasnya:
| Jenis batas nilai minimum | Batas |
|---|---|
| Per hari per project | 1.000.000 permintaan |
Untuk mengetahui informasi selengkapnya, lihat Model standar Google Workspace untuk alat dan API agen.
Mengatasi error kuota berbasis waktu
Untuk semua error berbasis waktu (maksimum N permintaan per X menit), sebaiknya kode Anda menangkap pengecualian dan menggunakan penundaan eksponensial yang dipangkas untuk memastikan perangkat Anda tidak menghasilkan beban yang berlebihan.
Backoff eksponensial adalah strategi penanganan error standar untuk aplikasi jaringan. Algoritma backoff eksponensial mencoba ulang permintaan menggunakan waktu tunggu yang meningkat secara eksponensial di antara permintaan, hingga waktu backoff maksimum. Jika permintaan masih gagal, penting agar penundaan antar-permintaan meningkat dari waktu ke waktu hingga permintaan berhasil.
Contoh algoritma
Algoritma backoff eksponensial mencoba ulang permintaan secara eksponensial, sehingga meningkatkan waktu tunggu antar-percobaan ulang hingga waktu backoff maksimum. Contoh:
- Buat permintaan ke Google Calendar API.
- Jika permintaan gagal, tunggu 1 +
random_number_millisecondsdetik dan coba lagi permintaan tersebut. - Jika permintaan gagal, tunggu 2 +
random_number_millisecondsdetik dan coba lagi permintaan tersebut. - Jika permintaan gagal, tunggu 4 +
random_number_millisecondsdan coba lagi permintaan tersebut. - Dan seterusnya, hingga
maximum_backoffkali. - Terus tunggu dan coba ulang hingga jumlah maksimum percobaan ulang, tetapi jangan tambah waktu tunggu antar-percobaan ulang.
dengan:
- Waktu tunggu adalah
min(((2^n)+random_number_milliseconds), maximum_backoff), dengannbertambah 1 untuk setiap iterasi (permintaan). random_number_millisecondsadalah jumlah acak milidetik yang kurang dari atau sama dengan 1.000. Hal ini membantu menghindari kasus saat banyak klien disinkronkan oleh beberapa situasi dan semua mencoba lagi secara bersamaan, sehingga mengirimkan permintaan dalam gelombang yang disinkronkan. Nilairandom_number_millisecondsdihitung ulang setelah setiap permintaan coba lagi.maximum_backoffbiasanya 32 atau 64 detik. Nilai yang sesuai bergantung pada kasus penggunaan.
Klien dapat terus mencoba ulang setelah mencapai waktu maximum_backoff.
Percobaan ulang setelah tahap ini tidak perlu terus meningkatkan waktu backoff. Misalnya, jika klien menggunakan waktu maximum_backoff 64 detik, setelah mencapai nilai ini, klien dapat mencoba lagi setiap 64 detik. Pada saat tertentu,
klien seharusnya dicegah untuk mencoba ulang tanpa batas waktu.
Waktu tunggu antara percobaan ulang dan jumlah percobaan ulang bergantung pada kasus penggunaan dan kondisi jaringan Anda.
Harga
Semua penggunaan standar Google Calendar API tersedia tanpa biaya tambahan. Melebihi batas permintaan kuota direncanakan akan menimbulkan biaya pada akun penagihan Google Cloud Anda pada tahun 2026. Untuk mengetahui informasi selengkapnya, lihat Model standar Google Workspace untuk alat dan API agen.
Meminta penambahan kuota
Bergantung pada penggunaan resource project, Anda mungkin ingin meminta penyesuaian kuota. Panggilan API oleh akun layanan dianggap menggunakan satu akun. Mengajukan permohonan untuk penyesuaian kuota belum tentu disetujui. Permintaan penyesuaian kuota yang akan meningkatkan nilai kuota secara signifikan membutuhkan waktu lebih lama untuk disetujui.
Tidak semua project memiliki kuota yang sama. Seiring meningkatnya penggunaan Google Cloud dari waktu ke waktu, nilai kuota Anda mungkin perlu ditingkatkan. Jika Anda memperkirakan adanya peningkatan penggunaan yang signifikan di masa mendatang, Anda dapat secara proaktif meminta penyesuaian kuota dari halaman Quotas & System Limits di konsol Google Cloud.
Untuk mempelajari lebih lanjut, lihat referensi berikut:
- Tentang penyesuaian kuota
- Melihat batas dan penggunaan kuota Anda
- Meminta batas kuota yang lebih tinggi
Memecahkan masalah
Jika salah satu kuota terlampaui, Anda akan dibatasi laju dan menerima kode status 403
usageLimits
atau kode status 429
usageLimits
sebagai respons terhadap kueri Anda.
Jika hal ini terjadi, Anda dapat mencoba langkah berikut:
Pastikan untuk mengikuti semua praktik terbaik: gunakan backoff eksponensial, acak pola traffic, dan gunakan notifikasi push.
Jika project Anda berkembang dan Anda memiliki lebih banyak pengguna, Anda dapat meminta penambahan kuota.
Jika Anda mencapai batas kuota per pengguna, Anda dapat melakukan hal berikut:
Jika Anda menggunakan akun layanan, alokasikan beban kepada pengguna atau bagi beban tersebut di antara beberapa akun layanan.
Meskipun Anda dapat meminta peningkatan kuota per pengguna, secara umum, sebaiknya jangan meningkatkan kuota di atas nilai default karena aplikasi Anda mungkin mulai mencapai jenis batas lainnya, misalnya, batas penggunaan kalender umum atau batas operasional.
Uji batas kuota Anda dengan mendaftarkan project khusus pengujian terpisah yang memiliki konfigurasi serupa dengan project produksi Anda. Untuk mengetahui informasi selengkapnya, lihat Penanganan batas kuota pengujian.
Mengacak pola traffic
Klien kalender rentan terhadap pola traffic yang tidak teratur yang disebabkan oleh beberapa klien yang melakukan operasi secara bersamaan. Misalnya, praktik buruk umum untuk klien Kalender adalah melakukan sinkronisasi penuh pada tengah malam. Hal ini hampir pasti akan menyebabkan kuota per menit Anda terlampaui dan mengakibatkan pembatasan kecepatan dan penghentian sementara.
Untuk menghindari hal ini, pastikan traffic Anda tersebar sepanjang hari jika memungkinkan. Jika klien Anda perlu melakukan sinkronisasi harian, minta klien menentukan waktu acak (berbeda untuk setiap klien). Jika Anda perlu melakukan operasi secara rutin, variasikan interval +/- 25%. Tindakan ini akan mendistribusikan traffic secara lebih merata dan memberikan pengalaman pengguna yang jauh lebih baik.
Menggunakan notifikasi push
Kasus penggunaan umum adalah melakukan tindakan setiap kali ada perubahan di kalender pengguna. Anti-pola di sini adalah melakukan polling berulang kali pada setiap kalender yang diminati. Tindakan ini akan sangat cepat menghabiskan semua kuota Anda. Misalnya, jika aplikasi Anda memiliki 5.000 pengguna dan melakukan polling kalender setiap pengguna sekali per menit, maka hal ini memerlukan kuota per menit setidaknya 5.000, bahkan sebelum ada pekerjaan yang dilakukan.
Aplikasi sisi server dapat mendaftar untuk menerima notifikasi push, yang memungkinkan kami memberi tahu Anda saat ada sesuatu yang menarik. Metode ini memerlukan lebih banyak upaya untuk
menyiapkannya, tetapi memungkinkan penggunaan kuota yang jauh lebih efisien, dan memberikan
pengalaman pengguna yang lebih baik. Pastikan Anda menentukan eventType yang ingin
Anda dapatkan notifikasinya. Untuk mengetahui informasi selengkapnya, lihat Notifikasi
push.
Alokasi yang tepat dengan akun layanan
Jika aplikasi Anda membuat permintaan menggunakan delegasi tingkat domain, secara default akun layanan akan ditagih terkait kuota "per menit per pengguna per project", bukan pengguna yang Anda tiru. Artinya, akun layanan kemungkinan akan kehabisan kuota dan dibatasi laju permintaannya, meskipun akun tersebut mungkin beroperasi di beberapa kalender pengguna.
Anda dapat menghindarinya dengan menggunakan parameter URL quotaUser (atau header HTTP x-goog-quota-user) untuk menunjukkan pengguna mana yang ditagih. Ini hanya digunakan untuk penghitungan kuota. Untuk mengetahui informasi selengkapnya, lihat Membatasi permintaan per pengguna.
Menguji penanganan batas kuota
Untuk memastikan aplikasi Anda dapat menangani batas kuota dengan baik dalam praktiknya (misalnya, melalui coba lagi dengan penghentian eksponensial) dan untuk meminimalkan potensi gangguan apa pun bagi pengguna Anda, sebaiknya uji skenario Anda di lingkungan yang sebenarnya.
Untuk melakukan pengujian tanpa mengganggu penggunaan aplikasi Anda yang sebenarnya, sebaiknya daftarkan project khusus pengujian terpisah di konsol Google Cloud, lalu konfigurasi layar izin OAuth dengan cara yang serupa dengan project produksi Anda. Kemudian, Anda dapat menetapkan batas kuota yang rendah secara buatan untuk project ini dan mengamati perilaku aplikasi Anda.