Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Limity wykorzystania

Interfejs Kalendarza Google API ma limity, które zapewniają sprawiedliwe korzystanie z niego przez wszystkich użytkowników. Podczas korzystania z interfejsu Calendar API należy pamiętać o 3 ważnych ograniczeniach:

Limity wykorzystania interfejsu API: egzekwowane na projekt i na użytkownika. Więcej informacji znajdziesz w artykule Rodzaje limitów wykorzystania interfejsu Calendar API.
Ogólne limity korzystania z Kalendarza Google: interfejs Google Calendar API to usługa współdzielona, która ma ograniczenia chroniące ogólną wydajność systemu Google Workspace. Więcej informacji znajdziesz w artykule Unikanie limitów korzystania z Kalendarza.
Limity operacyjne: te limity mogą zostać w dowolnym momencie ograniczone. Na przykład jeśli spróbujesz szybko zapisać dane w jednym kalendarzu.

Limity interfejsu Calendar API

Obowiązują 2 rodzaje limitów:

Na minutę na projekt: to liczba żądań, które projekt Google Cloud może wysłać w ciągu minuty.
Na minutę na użytkownika na projekt: to liczba żądań, które może wysłać dowolny użytkownik w Twoim projekcie w chmurze. Ten limit ma pomóc w zapewnieniu sprawiedliwego rozkładu wykorzystania wśród użytkowników.

Limity są obliczane co minutę przy użyciu okna przesuwnego. Nagły wzrost ruchu, który w ciągu minuty przekroczy limit na minutę, spowoduje ograniczenie szybkości w następnym okresie, aby zapewnić, że średnie wykorzystanie pozostanie w granicach limitów.

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

Typ limitu wykorzystania	Limit
Na minutę na projekt	10 tys. żądań
Za minutę na użytkownika na projekt	600 żądań

Dzienny próg naliczania należności

Ten limit dzienny na projekt określa maksymalną liczbę żądań, które Twój projekt Google Cloud może wykorzystać w ciągu 24 godzin, zanim zostaną naliczone opłaty.

Korzystanie z usług w ramach tego limitu nie wiąże się z dodatkowymi opłatami, a Twoje konto Google Cloud nie jest obciążane. Szczegółowe informacje o rozliczeniach zostaną udostępnione w 2026 roku z co najmniej 90-dniowym wyprzedzeniem przed wejściem w życie jakichkolwiek zmian.

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

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

Typ limitu progu	Limit
Dziennie na projekt	1 000 000 żądań

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

Rozwiązywanie problemów z limitami opartymi na czasie

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, używając wykładniczo rosnących czasów oczekiwania między żądaniami, aż do maksymalnego czasu do ponowienia. Jeśli żądania nadal są nieudane, ważne jest, aby opóźnienia między żądaniami z czasem się zwiększały, aż żądanie zostanie zrealizowane.

Przykładowy algorytm

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

Wysyłanie żądania do interfejsu Google Calendar API.
Jeśli żądanie się nie powiedzie, poczekaj 1 + random_number_milliseconds i spróbuj ponownie.
Jeśli żądanie się nie powiedzie, poczekaj 2 + random_number_milliseconds i spróbuj ponownie.
Jeśli prośba się nie powiedzie, poczekaj 4 + random_number_milliseconds i spróbuj ponownie.
I tak dalej, aż do maximum_backoff razy.
Kontynuuj oczekiwanie i ponawianie prób do osiągnięcia maksymalnej liczby prób, ale nie wydłużaj czasu oczekiwania między próbami.

gdzie:

Czas oczekiwania wynosi min(((2^n)+random_number_milliseconds), maximum_backoff), a wartość n jest zwiększana o 1 przy 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 synchronizowanych przez pewne zdarzenie i wszyscy ponawiają próbę w tym samym czasie, wysyłając żądania w zsynchronizowanych falach. Wartość random_number_milliseconds jest ponownie obliczana po każdej próbie ponowienia.
maximum_backoff wynosi zwykle 32 lub 64 sekundy. Odpowiednia wartość zależy od przypadku użycia.

Klient może ponawiać próby po osiągnięciu czasu maximum_backoff. Ponowne próby po tym momencie nie muszą już wydłużać czasu do ponowienia. Jeśli na przykład klient używa czasu maximum_backoff 64 sekund, 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 ponownymi próbami i liczba ponownych prób zależą od przypadku użycia i warunków sieciowych.

Ceny

Wszystkie standardowe funkcje interfejsu Kalendarza Google API są dostępne bez dodatkowych opłat. Przekroczenie limitów żądań będzie wiązać się z obciążaniem Twojego konta rozliczeniowego Google Cloud opłatami w późniejszym okresie 2026 r. Więcej informacji znajdziesz w artykule Ujednolicony model Google Workspace dla narzędzi agenta i interfejsów API.

Poproś o zwiększenie limitu

W zależności od wykorzystania zasobów w projekcie możesz poprosić o dostosowanie limitu. Wywołania interfejsu API przez konto usługi są traktowane jako korzystanie z jednego konta. Wysłanie wniosku o zwiększenie limitu nie gwarantuje jego zatwierdzenia. Zatwierdzenie próśb o dostosowanie limitu, które znacznie zwiększają 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 wartości limitów mogą wymagać zwiększenia. Jeśli spodziewasz się znacznego wzrostu wykorzystania, możesz z wyprzedzeniem poprosić o zmianę limitów na stronie Limity przydziału i limity systemu w konsoli Google Cloud.

Więcej informacji znajdziesz w tych materiałach:

Rozwiązywanie problemów

Jeśli przekroczysz którykolwiek z tych limitów, zostanie na Ciebie nałożone ograniczenie liczby zapytań i w odpowiedzi na zapytania otrzymasz kod stanu 403 usageLimits lub 429 usageLimits.

W takim przypadku możesz wykonać te czynności:

Stosuj wszystkie sprawdzone metody: używaj wycofywania wykładniczego, losowych wzorców ruchu i powiadomień push.
Jeśli Twój projekt się rozwija i masz więcej użytkowników, możesz poprosić o zwiększenie limitu.
Jeśli osiągniesz limity na użytkownika, możesz wykonać te czynności:
- Jeśli używasz konta usługi, przydziel obciążenie użytkownikom lub rozdziel je między kilka kont usługi.
- Możesz poprosić o zwiększenie limitu na użytkownika, ale generalnie nie zalecamy zwiększania go powyżej wartości domyślnej, ponieważ aplikacja może zacząć osiągać inne rodzaje limitów, np. ogólne limity wykorzystania Kalendarza lub limity operacyjne.
Sprawdź limity, rejestrując osobny projekt testowy o konfiguracji podobnej do projektu produkcyjnego. Więcej informacji znajdziesz w artykule Testowanie obsługi limitów.

Losowe wzorce ruchu

Klienci kalendarza są podatni na gwałtowne wzrosty ruchu spowodowane przez wielu klientów wykonujących operacje w tym samym czasie. Na przykład częstym błędem w przypadku klienta Kalendarza jest przeprowadzanie pełnej synchronizacji o północy. Prawie na pewno doprowadzi to do przekroczenia limitu na minutę i spowoduje ograniczenie szybkości oraz wycofanie.

Aby tego uniknąć, w miarę możliwości rozłóż ruch na cały dzień. Jeśli klient musi przeprowadzać codzienną synchronizację, powinien wybrać losową godzinę (inną dla każdego klienta). Jeśli musisz regularnie wykonywać operację, zmieniaj interwał o +/- 25%. Dzięki temu ruch będzie bardziej równomierny, a użytkownicy będą mogli wygodniej korzystać z witryny.

Korzystanie z powiadomień push

Częstym zastosowaniem jest wykonywanie działania za każdym razem, gdy coś się zmieni w kalendarzu użytkownika. Antywzorcem jest wielokrotne odpytywanie każdego kalendarza, który Cię interesuje. Bardzo szybko wykorzystasz w ten sposób cały limit. Jeśli na przykład Twoja aplikacja ma 5000 użytkowników i co minutę odpytuje kalendarz każdego z nich, wymaga to limitu co najmniej 5000 żądań na minutę, jeszcze zanim wykona jakiekolwiek działanie.

Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, co pozwala nam informować Cię o interesujących Cię wydarzeniach. Ich skonfigurowanie wymaga więcej pracy, ale pozwalają one znacznie efektywniej wykorzystywać limit i zapewniają lepszą obsługę użytkowników. Określ eventType, o których chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w sekcji Powiadomienia push.

Prawidłowe przydzielanie za pomocą kont usługi

Jeśli aplikacja wysyła żądania za pomocą przekazywania dostępu w całej domenie, domyślnie opłaty za limity „na minutę na użytkownika na projekt” są naliczane na konto usługi, a nie na użytkownika, którego tożsamość jest używana. Oznacza to, że konto usługi prawdopodobnie wyczerpie limit i zostanie objęte ograniczeniem liczby żądań, nawet jeśli działa w kalendarzach wielu użytkowników.

Aby tego uniknąć, użyj parametru adresu URL quotaUser (lub nagłówka HTTP x-goog-quota-user), aby wskazać, który użytkownik ma zostać obciążony. Jest on używany tylko do obliczania limitów. Więcej informacji znajdziesz w sekcji Ograniczanie liczby żądań na użytkownika.

Testowanie obsługi limitów

Aby mieć pewność, że aplikacja będzie prawidłowo obsługiwać osiąganie limitów w praktyce (np. przez ponawianie prób z wykładniczym wycofywaniem) i zminimalizować potencjalne zakłócenia dla użytkowników, zdecydowanie zalecamy przetestowanie scenariusza w rzeczywistym środowisku.

Aby przeprowadzić testy bez zakłócania działania prawdziwej aplikacji, zalecamy zarejestrowanie w konsoli Google Cloud osobnego projektu przeznaczonego tylko do testów, a następnie skonfigurowanie ekranu zgody OAuth w sposób podobny do projektu produkcyjnego. Następnie możesz ustawić sztucznie niskie limity dla tego projektu i obserwować zachowanie aplikacji.

Limity serwera MCP Kalendarza

Serwer MCP Kalendarza używa wskaźnika alokacji kosztów zapytań. W tabelach poniżej znajdziesz szczegółowe informacje o koszcie zapytania dla każdej metody serwera MCP Kalendarza, podzielone na sekcje:

Limity MCP w Kalendarzu