Batas penggunaan

Google Calendar API memiliki kuota untuk memastikan bahwa API ini digunakan secara adil oleh semua pengguna. Pertimbangkan tiga batasan penting 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 Kalender umum: 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 diterapkan kapan saja. Misalnya, batas mungkin berlaku 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 oleh 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 membantu 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 akan menyebabkan 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 oleh project 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 akhir 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 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 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 dan coba lagi permintaan tersebut.
  3. Jika permintaan gagal, tunggu 2 + random_number_milliseconds dan coba lagi permintaan tersebut.
  4. Jika permintaan gagal, tunggu 4 + random_number_milliseconds dan coba lagi permintaan tersebut.
  5. Dan seterusnya, hingga waktu maximum_backoff.
  6. Lanjutkan menunggu dan mencoba 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), dengan n bertambah 1 untuk setiap iterasi (permintaan).
  • random_number_milliseconds adalah jumlah acak milidetik 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 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 dikenai biaya ke akun penagihan Google Cloud Anda pada akhir 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:

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

Untuk menghindarinya, sebarkan traffic Anda 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 mendistribusikan traffic secara lebih merata dan memberikan pengalaman pengguna yang 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 setiap kalender yang diminati. Hal ini akan menghabiskan kuota Anda dengan cepat. Misalnya, jika aplikasi Anda memiliki 5.000 pengguna dan melakukan polling 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 Kalender memberi tahu Anda saat ada sesuatu yang menarik. Notifikasi ini memerlukan lebih banyak upaya untuk disiapkan, tetapi memungkinkan Anda menggunakan kuota secara lebih efisien dan memberikan pengalaman pengguna yang lebih baik. Tentukan eventType yang notifikasinya Anda inginkan. 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 untuk kuota "per menit per pengguna per project", bukan pengguna yang Anda tiru. Artinya, akun layanan kemungkinan akan menghabiskan kuotanya 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 yang dikenai biaya. Google hanya menggunakan parameter ini untuk penghitungan kuota. Untuk mengetahui informasi selengkapnya, lihat Membatasi permintaan per pengguna.

Menguji penanganan batas kuota

Untuk memastikan bahwa aplikasi Anda menangani pencapaian batas kuota dengan baik dalam praktiknya (misalnya, melalui percobaan ulang dengan backoff eksponensial) dan untuk meminimalkan potensi gangguan pada pengguna Anda, uji aplikasi Anda di lingkungan yang realistis.

Untuk menguji tanpa mengganggu penggunaan aplikasi Anda yang sebenarnya, daftarkan project khusus pengujian terpisah di konsol Google Cloud lalu konfigurasi layar izin OAuth dengan cara yang mirip 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 untuk project Cloud Anda selama satu menit.

  • Per menit per pengguna per project: Ini adalah biaya kueri yang dapat dikenakan oleh satu pengguna di project Cloud Anda dalam satu menit.

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.