Batas penggunaan

Google Calendar API memiliki kuota untuk memastikan bahwa API ini 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 mengetahui 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

• Batas operasional: Batas 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 membantu Anda memastikan distribusi penggunaan yang adil di antara pengguna.

Kuota dihitung per menit menggunakan jendela geser. Lonjakan traffic yang cepat dan melebihi kuota per menit Anda selama satu menit akan mengakibatkan pembatasan kapasitas selama jendela berikutnya untuk memastikan bahwa, rata-rata, penggunaan Anda tetap berada dalam kuota.

Tabel berikut memerinci batas ini:

Jenis batas penggunaan	Batas
Per menit per project	10.000 permintaan
Per menit per pengguna per project	600 permintaan

Batas nilai minimum penagihan harian

Batas per hari per project ini menentukan jumlah maksimum permintaan yang dapat digunakan project Google Cloud Anda dalam periode 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 minimal 90 hari sebelum perubahan apa pun berlaku.

Anda tidak dapat meminta penambahan batas nilai minimum harian ini.

Tabel berikut memerinci batas tersebut:

Jenis batas nilai minimum	Batas
Per hari per project	1.000.000 permintaan

Untuk mengetahui informasi selengkapnya, lihat Model standar Google Workspace untuk alat agen dan API.

Mengatasi error kuota berbasis waktu

Untuk semua error berbasis waktu (maksimum N permintaan per X menit), sebaiknya kode Anda menangkap pengecualian dan menggunakan backoff eksponensial terpotong 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 untuk meningkatkan penundaan antara permintaan 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:

1. Buat permintaan ke Google Calendar API.
2. Jika permintaan gagal, tunggu 1 + random_number_milliseconds, lalu coba lagi permintaan.
3. Jika permintaan gagal, tunggu 2 + random_number_milliseconds, lalu coba lagi permintaan.
4. Jika permintaan gagal, tunggu 4 + random_number_milliseconds, lalu coba lagi permintaan.
5. Dan seterusnya, hingga waktu maximum_backoff.
6. Terus tunggu dan coba lagi hingga jumlah percobaan ulang maksimum, tetapi jangan tingkatkan periode tunggu antar-percobaan ulang.

dengan:

• Waktu tunggu adalah min(((2^n)+random_number_milliseconds), maximum_backoff), dengan n bertambah 1 untuk setiap iterasi (permintaan).
• random_number_milliseconds adalah jumlah milidetik acak yang kurang dari atau sama dengan 1.000. Hal ini membantu menghindari kasus saat banyak klien disinkronkan oleh situasi tertentu dan semua mencoba lagi secara bersamaan, sehingga mengirimkan permintaan dalam gelombang yang disinkronkan. Nilai random_number_milliseconds dihitung ulang setelah setiap permintaan coba lagi.
• maximum_backoff biasanya 32 atau 64 detik. Nilai yang sesuai bergantung pada kasus penggunaan.

Klien dapat terus mencoba lagi 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 suatu titik, klien harus dicegah untuk mencoba lagi tanpa batas.

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 dikenai biaya ke 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, 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 mungkin memerlukan 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 Kuota & Batas Sistem di konsol Google Cloud.

Untuk mempelajari lebih lanjut, lihat referensi berikut:

• Tentang penyesuaian kuota
• Melihat batas dan penggunaan kuota
• Meminta batas kuota yang lebih tinggi

Memecahkan masalah

Jika salah satu kuota terlampaui, Anda akan dibatasi kapasitasnya dan menerima 403 usageLimits kode status atau 429 usageLimits kode status sebagai respons terhadap kueri Anda.

Jika hal ini terjadi, Anda dapat mencoba hal berikut:

1. Pastikan untuk mengikuti semua praktik terbaik: gunakan backoff eksponensial, acak pola traffic, dan gunakan notifikasi push.

2. Jika project Anda berkembang dan Anda memiliki lebih banyak pengguna, Anda dapat meminta penambahan kuota kuota.

3. Jika Anda mencapai batas kuota per pengguna, Anda dapat melakukan hal berikut:

   • Jika Anda menggunakan akun layanan, alokasikan beban ke pengguna atau bagi beban tersebut di antara beberapa akun layanan.

   • Meskipun Anda dapat meminta penambahan kuota per pengguna, secara umum, sebaiknya jangan menambahnya di atas nilai default karena aplikasi Anda mungkin mulai mencapai jenis batas lainnya, misalnya, batas penggunaan kalender umum atau batas operasional.

4. Uji batas kuota Anda dengan mendaftarkan project khusus pengujian terpisah yang memiliki konfigurasi serupa dengan project produksi Anda. Untuk mengetahui informasi selengkapnya, lihat Menguji penanganan batas kuota.

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 Anda melebihi kuota per menit dan mengakibatkan pembatasan kapasitas dan backoff.

Untuk menghindarinya, 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%. Hal 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. Antipola di sini adalah melakukan polling berulang kali pada setiap kalender yang diminati. Hal ini akan menghabiskan semua kuota Anda dengan sangat cepat. Misalnya, jika aplikasi Anda memiliki 5.000 pengguna dan melakukan polling pada kalender setiap pengguna sekali per menit, hal ini memerlukan kuota per menit minimal 5.000, bahkan sebelum pekerjaan apa pun dilakukan.

Aplikasi sisi server dapat mendaftar untuk notifikasi push, yang memungkinkan kami memberi tahu Anda saat ada hal yang menarik terjadi. Hal ini memerlukan lebih banyak upaya untuk disiapkan, tetapi memungkinkan penggunaan kuota Anda yang jauh lebih efisien, dan memberikan pengalaman pengguna yang lebih baik. Pastikan Anda menentukan eventType yang ingin Anda terima notifikasinya. Untuk mengetahui informasi selengkapnya, lihat Notifikasi push.

Alokasi yang tepat dengan akun layanan

Jika aplikasi Anda melakukan permintaan menggunakan delegasi tingkat domain, secara default akun layanan akan dikenai biaya terkait kuota "per menit per pengguna per project", bukan pengguna yang Anda tiru. Artinya, akun layanan kemungkinan akan kehabisan kuota dan dibatasi kapasitasnya, meskipun mungkin beroperasi di kalender beberapa pengguna.

Anda dapat menghindarinya dengan menggunakan parameter URL quotaUser (atau header HTTP x-goog-quota-user) untuk menunjukkan pengguna mana yang dikenai biaya. Parameter ini hanya digunakan untuk perhitungan kuota. Untuk mengetahui informasi selengkapnya, lihat Membatasi permintaan per pengguna.

Menguji penanganan batas kuota

Untuk memastikan bahwa aplikasi Anda dapat menangani pencapaian batas kuota dengan baik dalam praktiknya (misalnya, melalui percobaan ulang dengan eksponensial backoff) dan untuk meminimalkan potensi gangguan apa pun kepada pengguna, sebaiknya uji skenario Anda di lingkungan yang sebenarnya.

Untuk menguji 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 kuota yang sangat rendah untuk project ini dan mengamati perilaku aplikasi Anda.

Kuota server MCP Kalender

Server MCP Kalender menggunakan metrik alokasi biaya kueri. Tabel berikut memerinci biaya kueri untuk setiap metode server MCP Kalender berdasarkan bagian:

Kuota MCP Kalender

Dua jenis kuota diterapkan:

• Per menit per project: Ini adalah biaya kueri ke project Google Cloud Anda selama satu menit.

• Per menit per pengguna per project: Ini adalah biaya kueri ke project Google Cloud Anda selama satu menit yang dapat digunakan oleh satu pengguna tertentu.

Tabel berikut memerinci kuota ini:

Jenis batas penggunaan	Biaya kueri
Per menit per project	10.000
Per menit per pengguna per project	600

Kuota kumpulan alat MCP Kalender

Tabel berikut memerinci biaya kueri untuk setiap kumpulan alat calendarmcp.googleapis.com:

Endpoint	Alat	Biaya kueri
/mcp/v1	create_event	1
	delete_event	10
	get_event	1
	list_events	1
	respond_to_event	1
	search_events	1
	update_event	1
	suggest_time	1
	list_calendars	1

Untuk mengetahui informasi selengkapnya, lihat Referensi Calendar MCP API.

Topik terkait

• Mengirim permintaan serempak
• Tips performa
• Menghindari batas penggunaan Kalender