Batas penggunaan

Google Sheets API adalah layanan bersama, dan kami menerapkan kuota dan batasan untuk melindungi performa keseluruhan sistem Google Workspace bagi semua pengguna.

Batas kuota

Meskipun Sheets API tidak memiliki batas ukuran yang ketat untuk permintaan API, pengguna mungkin mengalami batasan dari berbagai komponen pemrosesan yang tidak dikontrol oleh Google Sheets. Untuk mempercepat permintaan, sebaiknya gunakan payload maksimum 2 MB.

Sheets API memiliki kuota per menit, dan kuota tersebut diisi ulang setiap menit. Misalnya, ada batas permintaan baca sebanyak 300 per menit per project. Jika aplikasi Anda mengirim 350 permintaan dalam satu menit, 50 permintaan tambahan akan melebihi kuota dan menghasilkan respons kode status HTTP 429: Too many requests. Jika hal ini terjadi, Anda harus menggunakan algoritma backoff eksponensial. Setelah 1 menit, Anda dapat menjalankan permintaan lagi.

Tabel berikut menjelaskan batas permintaan:

Kuota
Permintaan baca
Per menit per project 300
Per menit per pengguna per project 60
Permintaan tulis
Per menit per project 300
Per menit per pengguna per project 60

Untuk mengetahui detail tentang batas file, lihat File yang dapat Anda simpan di Google Drive.

Perilaku dan batasan

Saat Anda menggunakan Sheets API, perhatikan perilaku dan batasan berikut yang memengaruhi kuota Anda:

  • Permintaan baca adalah panggilan ke metode apa pun yang mengambil data dari spreadsheet, seperti get atau search. Permintaan tulis adalah panggilan ke metode apa pun yang mengubah spreadsheet, seperti update, clear, atau copyTo.

  • Pengguna dapat mengirim beberapa permintaan secara bersamaan, asalkan tidak melebihi batas kuota. Setiap permintaan batch, termasuk subpermintaan apa pun, dihitung sebagai satu permintaan API terhadap batas penggunaan Anda.

  • Semua permintaan Sheets diterapkan secara atomik. Artinya, jika ada permintaan yang tidak valid, seluruh update akan gagal dan tidak ada perubahan (yang mungkin bergantung) yang diterapkan.

  • Ada batas waktu maksimum untuk memproses satu permintaan API. Saat Sheets memproses permintaan selama lebih dari 180 detik, permintaan akan menampilkan error waktu tunggu habis.

  • Selama Anda tidak melebihi kuota per menit, tidak ada batasan jumlah permintaan yang dapat Anda buat per hari.

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 antar-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 Sheets API.
  2. Jika permintaan gagal, tunggu 1 + random_number_milliseconds, lalu coba lagi permintaan tersebut.
  3. Jika permintaan gagal, tunggu 2 + random_number_milliseconds, lalu coba lagi permintaan tersebut.
  4. Jika permintaan gagal, tunggu 4 + random_number_milliseconds, lalu coba lagi permintaan tersebut.
  5. Dan seterusnya, hingga waktu maximum_backoff.
  6. Terus tunggu dan coba lagi hingga jumlah percobaan ulang maksimum tertentu, 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 Sheets API tersedia tanpa biaya tambahan. Melebihi batas permintaan kuota 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 waktu, saat Anda semakin sering menggunakan Google Cloud, 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:

Kuota server MCP Sheets

Server MCP Sheets menggunakan metrik permintaan baca dan tulis. Tabel berikut menjelaskan kuota dan biaya kueri untuk setiap metode server MCP Sheets berdasarkan bagian:

Kuota MCP Sheets

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 menjelaskan kuota ini:

Kuota
Permintaan baca
Per menit per project 300
Per menit per pengguna per project 60
Permintaan tulis
Per menit per project 300
Per menit per pengguna per project 60

Kuota toolset MCP Sheets

Tabel berikut menjelaskan biaya kueri untuk setiap toolset sheetsmcp.googleapis.com:

Endpoint Alat Biaya kueri
/mcp/v1 get_values 1 permintaan baca
get_spreadsheet 1 permintaan baca
update_spreadsheet 1 permintaan tulis
update_values 1 permintaan tulis
update_formulas 1 permintaan tulis
insert_dimension 1 permintaan tulis

Untuk mengetahui informasi selengkapnya, lihat Referensi API MCP Sheets.