Limity wykorzystania

Interfejs Google Sheets API jest usługą współdzieloną, dlatego stosujemy limity i ograniczenia, aby chronić ogólną wydajność systemu Google Workspace dla wszystkich użytkowników.

Limity przydziału

Interfejs Sheets API nie ma sztywnych limitów rozmiaru żądania do interfejsu API, ale użytkownicy mogą napotkać limity różnych komponentów przetwarzania, które nie są kontrolowane przez Arkusze Google. Aby przyspieszyć żądania, zalecamy, aby maksymalny rozmiar ładunku wynosił 2 MB.

Interfejs Sheets API ma limity na minutę, które są odnawiane co minutę. Na przykład limit żądań odczytu wynosi 300 na minutę na projekt. Jeśli aplikacja wyśle 350 żądań w ciągu minuty, dodatkowe 50 żądań przekroczy limit i wygeneruje odpowiedź z kodem stanu HTTP 429: Too many requests. W takim przypadku należy użyć algorytmu wzrastającego czasu do ponowienia. Po upływie 1 minuty możesz ponownie wykonywać żądania.

W tabeli poniżej znajdziesz szczegółowe informacje o limitach żądań:

Limity
Żądania odczytu
Na minutę na projekt 300
Na minutę na użytkownika na projekt 60
Żądania zapisu
Na minutę na projekt 300
Na minutę na użytkownika na projekt 60

Szczegółowe informacje o limitach plików znajdziesz w artykule Pliki, które możesz przechowywać na Dysku Google.

Zachowanie i ograniczenia

Podczas pracy z interfejsem Sheets API zwróć uwagę na te działania i ograniczenia, które wpływają na limity:

  • Żądania odczytu to wywołania dowolnej metody, która pobiera dane z arkusza kalkulacyjnego, np. get lub search. Żądania zapisu to wywołania dowolnej metody, która zmienia arkusz kalkulacyjny, np. update, clear lub copyTo.

  • Użytkownicy mogą przesyłać wiele żądań jednocześnie, o ile nie przekraczają limitu. Każde żądanie zbiorcze, w tym każde żądanie podrzędne, jest liczone jako 1 żądanie interfejsu API w ramach limitu wykorzystania.

  • Wszystkie żądania Arkuszy są stosowane atomowo. Oznacza to, że jeśli którekolwiek żądanie jest nieprawidłowe, cała aktualizacja się nie powiedzie i żadne (potencjalnie zależne) zmiany nie zostaną zastosowane.

  • Istnieje maksymalny limit czasu przetwarzania 1 żądania do interfejsu API. Gdy Arkusze przetwarzają żądanie dłużej niż 180 sekund, żądanie zwraca błąd przekroczenia limitu czasu.

  • O ile nie przekraczasz limitów na minutę, nie ma ograniczeń co do liczby żądań, które możesz wysłać dziennie.

Rozwiązywanie błędów limitu czasu

W przypadku wszystkich błędów związanych z czasem (maksymalnie N żądań na X minut) zalecamy aby kod przechwytywał wyjątek i używał skróconego wzrastającego czasu do ponowienia, aby urządzenia nie generowały nadmiernego obciążenia.

Wzrastający czas do ponowienia to standardowa strategia obsługi błędów w przypadku aplikacji sieciowych. Algorytm wzrastającego czasu do ponowienia ponawia żądania, używając wykładniczo rosnących czasów oczekiwania między żądaniami, aż do maksymalnego czasu do ponowienia. Jeśli żądania nadal się nie powiodą, ważne jest, aby opóźnienia między żądaniami z czasem się zwiększały, aż żądanie się powiedzie.

Przykładowy algorytm

Algorytm wzrastającego czasu do ponowienia ponawia żądania wykładniczo, zwiększając czas oczekiwania między ponowieniami aż do maksymalnego czasu do ponowienia. Na przykład:

  1. Wyślij żądanie do interfejsu Google Sheets API.
  2. Jeśli żądanie się nie powiedzie, poczekaj 1 + random_number_milliseconds i ponów żądanie.
  3. Jeśli żądanie się nie powiedzie, poczekaj 2 + random_number_milliseconds i ponów żądanie.
  4. Jeśli żądanie się nie powiedzie, poczekaj 4 + random_number_milliseconds i ponów żądanie.
  5. I tak dalej, aż do czasu maximum_backoff.
  6. Kontynuuj oczekiwanie i ponawianie prób aż do maksymalnej liczby ponowień, ale nie zwiększaj czasu oczekiwania między ponowieniami.

gdzie:

  • Czas oczekiwania to min(((2^n)+random_number_milliseconds), maximum_backoff), a n jest zwiększane o 1 w każdej iteracji (żądaniu).
  • random_number_milliseconds to losowa liczba milisekund mniejsza lub równa 1000. Pomaga to uniknąć sytuacji, w których wielu klientów jest zsynchronizowanych przez jakąś sytuację i wszyscy ponawiają próbę jednocześnie, wysyłając żądania w zsynchronizowanych falach. Wartość random_number_milliseconds jest ponownie obliczana po każdym żądaniu ponowienia.
  • maximum_backoff to zwykle 32 lub 64 sekundy. Odpowiednia wartość zależy od przypadku użycia.

Klient może kontynuować ponawianie prób po osiągnięciu czasu maximum_backoff. Ponowienia po tym momencie nie muszą zwiększać czasu do ponowienia. Jeśli na przykład klient używa czasu maximum_backoff wynoszącego 64 sekundy, po osiągnięciu tej wartości może ponawiać próbę co 64 sekundy. W pewnym momencie, należy uniemożliwić klientom ponawianie prób w nieskończoność.

Czas oczekiwania między ponowieniami i liczba ponowień zależą od przypadku użycia i warunków sieciowych.

Ceny

Standardowe korzystanie z interfejsu Google Sheets API jest bezpłatne. Przekroczenie limitów żądań będzie wiązać się z obciążeniem konta rozliczeniowego Google Cloud opłatami w późniejszym okresie 2026 roku. Więcej informacji znajdziesz w artykule Standardowy model Google Workspace dla narzędzi i interfejsów API agenta.

Poproś o zwiększenie limitu

W zależności od wykorzystania zasobów projektu możesz poprosić o zmianę limitu. Wywołania interfejsu API przez konto usługi są traktowane jako korzystanie z jednego konta. Wysłanie wniosku o zmianę limitu nie gwarantuje jego zatwierdzenia. Zatwierdzenie próśb o zmianę limitu, które znacznie zwiększyłyby jego wartość, może potrwać dłużej.

Nie wszystkie projekty mają takie same limity. W miarę upływu czasu i zwiększania wykorzystania Google Cloud może być konieczne zwiększenie wartości limitu. Jeśli przewidujesz znaczny wzrost wykorzystania, możesz aktywnie poprosić o zmianę limitu na stronie Limity i ograniczenia systemu w konsoli Google Cloud.

Więcej informacji znajdziesz w tych materiałach: