Limity wykorzystania

Interfejs Gmail API podlega limitom wykorzystania, które ograniczają częstotliwość wywoływania jego metod. Limity są określane w jednostkach przydziału jednostek, czyli abstrakcyjnych jednostkach miary reprezentujących wykorzystanie zasobów Gmaila.

Limity interfejsu Gmail API

Obowiązują 2 typy limitów:

  • Na minutę na projekt: liczba jednostek limitu, których projekt w chmurze Google Cloud może użyć w ciągu minuty.

  • Na minutę na użytkownika na projekt: liczba jednostek przydziału, których może użyć dowolny użytkownik w projekcie w chmurze. Ten limit ma pomóc w zapewnieniu sprawiedliwego podziału wykorzystania między użytkowników.

W tabeli poniżej znajdziesz szczegółowe informacje o tych limitach:

Typ limitu wykorzystania Limit
Na minutę na projekt 1 200 000 jednostek limitu
Na minutę na użytkownika na projekt 6000 jednostek limitu

Informacje o obsłudze błędów związanych z limitami znajdziesz w artykule Rozwiązywanie błędów.

Dzienny próg naliczania należności

Ten limit dzienny na projekt określa maksymalną liczbę jednostek przydziału, których projekt Google Cloud może użyć w ciągu 24 godzin, zanim zostaną naliczone opłaty.

Wykorzystanie poniżej tego progu nie wiąże się z dodatkowymi opłatami, a Twoje konto Google Cloud nie jest obciążane. Pełne informacje o rozliczeniach udostępnimy w 2026 r. z co najmniej 90-dniowym wyprzedzeniem przed wprowadzeniem zmian.

Nie możesz poprosić o zwiększenie tego dziennego limitu.

W tabeli poniżej znajdziesz szczegółowe informacje o limicie:

Typ limitu progu Limit
Na dzień na projekt 80 000 000 jednostek przydziału

Więcej informacji znajdziesz w artykule Ustandaryzowany model Google Workspace dla narzędzi agentów i interfejsów API.

Wykorzystanie limitu na metodę

Liczba jednostek przydziału zużytych na żądanie różni się w zależności od wywoływanej metody. W tabeli poniżej znajdziesz informacje o wykorzystaniu jednostek przydziału na metodę:

Metoda Jednostki limitu
drafts.create 10
drafts.delete 10
drafts.get 20
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 20
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 40
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Podczas korzystania z interfejsu Gmail API obowiązuje też limit 500 odbiorców na e-maila.

Rozwiązywanie błędów związanych z limitami czasowymi

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 aplikacjach sieciowych. Algorytm wzrastającego czasu do ponowienia ponawia żądania z wykładniczo rosnącym czasem 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 Gmail API.
  2. Jeśli żądanie się nie powiedzie, odczekaj 1 + random_number_milliseconds i ponów żądanie.
  3. Jeśli żądanie się nie powiedzie, odczekaj 2 + random_number_milliseconds i ponów żądanie.
  4. Jeśli żądanie się nie powiedzie, odczekaj 4 + random_number_milliseconds i ponów żądanie.
  5. I tak dalej, aż do czasu maximum_backoff.
  6. Kontynuuj oczekiwanie i ponawianie 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 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 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 Gmail API jest bezpłatne. Przekroczenie limitów żądań przydziału spowoduje obciążenie Twojego konta rozliczeniowego Google Cloud w dalszej części 2026 r. Więcej informacji znajdziesz w artykule Ustandaryzowany model Google Workspace dla narzędzi i interfejsów API agentów.

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ą te 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: