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ą, że wszyscy użytkownicy korzystają z niego w sposób sprawiedliwy. 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 Typy 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 przekroczenia limitów korzystania z Kalendarza.
Limity operacyjne: te limity mogą zostać ograniczone w dowolnym momencie. Na przykład jeśli spróbujesz szybko zapisać dane w jednym kalendarzu.

Limity interfejsu Calendar API

Obowiązują 2 typy limitów:

Na minutę na projekt: jest to liczba żądań, które Twój projekt Google Cloud może wysłać w ciągu 1 minuty.
Na minutę na użytkownika na projekt: jest to liczba żądań, które może wysłać dowolny użytkownik w Twoim projekcie w chmurze. Ten limit ma na celu zapewnienie sprawiedliwego rozkładu wykorzystania między użytkowników.

Limity są obliczane na minutę przy użyciu okna przesuwnego. Gwałtowny wzrost ruchu, który przekroczy limit na minutę w ciągu 1 minuty, spowoduje ograniczenie liczby żądań w następnym oknie, 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 000 żądań
Na minutę na użytkownika na projekt	600 żądań

Dzienny próg rozliczeniowy

Ten limit na dzień 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.

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 tym limicie:

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

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

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 rosły z czasem, 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:

Wyślij żądanie do interfejsu Google Calendar API.
Jeśli żądanie się nie powiedzie, odczekaj 1 + random_number_milliseconds i ponów żądanie.
Jeśli żądanie się nie powiedzie, odczekaj 2 + random_number_milliseconds i ponów żądanie.
Jeśli żądanie się nie powiedzie, odczekaj 4 + random_number_milliseconds i ponów żądanie.
I tak dalej, aż do czasu maximum_backoff.
Kontynuuj oczekiwanie i ponawianie próby 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óby 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óby 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 Kalendarz Google API jest bezpłatne. Przekroczenie limitów żądań 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 agenta.

Poproś o zwiększenie limitu

W zależności od wykorzystania zasobów w projekcie 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 coraz częstszego korzystania z Google Cloud wartości limitów mogą wymagać zwiększenia. Jeśli przewidujesz znaczny wzrost wykorzystania w najbliższym czasie, możesz aktywnie poprosić o zmianę limitów na stronie Limity i ograniczenia systemu w konsoli Google Cloud.

Więcej informacji znajdziesz w tych materiałach:

Rozwiązywanie problemów

Jeśli którykolwiek limit zostanie przekroczony, liczba żądań zostanie ograniczona, a w odpowiedzi na zapytania otrzymasz kod stanu 403 usageLimits lub 429 usageLimits.

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

Stosuj wszystkie sprawdzone metody: używaj wzrastającego czasu do ponowienia, losowych wzorców ruchu, i używaj 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, rozdziel obciążenie między użytkowników lub podziel je między kilka kont usługi.
- Możesz poprosić o zwiększenie limitu na użytkownika, ale ogólnie nie zalecamy zwiększania go powyżej wartości domyślnej, ponieważ Twoja aplikacja może zacząć osiągać inne limity, np. ogólne limity korzystania z Kalendarza lub limity operacyjne.
Przetestuj limity, rejestrując osobny projekt testowy, który ma podobną konfigurację do projektu produkcyjnego. Więcej informacji znajdziesz w artykule Testowanie obsługi limitów.

Losowe wzorce ruchu

Klienci Kalendarza są podatni na nagłe wzrosty ruchu spowodowane wykonywaniem operacji przez wielu klientów w tym samym czasie. Na przykład częstą złą praktyką w przypadku klienta Kalendarza jest przeprowadzanie pełnej synchronizacji o północy. Prawie na pewno spowoduje to przekroczenie limitu na minutę i ograniczenie liczby żądań oraz ponowienia.

Aby tego uniknąć, zadbaj o to, aby ruch był rozłożony na cały dzień. Jeśli klient musi przeprowadzić codzienną synchronizację, niech określi losową godzinę (inną dla każdego klienta). Jeśli musisz regularnie wykonywać operację, zmieniaj interwał o +/- 25%. Spowoduje to bardziej równomierne rozłożenie ruchu i zapewni użytkownikom znacznie lepsze wrażenia.

Używanie powiadomień push

Częstym przypadkiem użycia jest wykonywanie działania, gdy coś się zmieni w kalendarzu użytkownika. Złą praktyką jest tutaj wielokrotne odpytywanie każdego interesującego kalendarza. Bardzo szybko wykorzystasz w ten sposób cały limit. Jeśli na przykład Twoja aplikacja ma 5000 użytkowników i odpytuje kalendarz każdego użytkownika raz na minutę, wymaga to limitu na minutę wynoszącego co najmniej 5000, jeszcze zanim zostanie wykonana jakakolwiek praca.

Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, co pozwala nam powiadamiać Cię, gdy wydarzy się coś interesującego. Wymagają one więcej pracy przy konfiguracji, ale pozwalają na znacznie bardziej efektywne wykorzystanie limitu i zapewniają lepsze wrażenia użytkownikom. Określ eventType, o którym chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w artykule Powiadomienia push.

Prawidłowe przydzielanie za pomocą kont usługi

Jeśli Twoja aplikacja wysyła żądania za pomocą przekazywania dostępu w całej domenie, domyślnie konto usługi jest obciążane w odniesieniu do limitów "na minutę na użytkownika na projekt", a nie użytkownik, którego reprezentujesz. 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 jest obciążany. Jest to używane tylko do obliczania limitów. Więcej informacji znajdziesz w artykule Ograniczanie liczby żądań na użytkownika.

Testowanie obsługi limitów

Aby mieć pewność, że Twoja aplikacja może prawidłowo obsługiwać osiąganie limitów w praktyce (np. przez ponawianie próby z wzrastającym czasem do ponowienia) i zminimalizować potencjalne zakłócenia dla użytkowników, zdecydowanie zalecamy przetestowanie scenariusza w rzeczywistym środowisku.

Aby przeprowadzić test bez zakłócania rzeczywistego korzystania z aplikacji, zalecamy zarejestrowanie osobnego projektu testowego w konsoli Google Cloud, a następnie skonfigurowanie ekranu zgody OAuth w sposób podobny do projektu produkcyjnego. Możesz wtedy ustawić sztucznie niskie limity dla tego projektu i obserwować zachowanie aplikacji.

Limity serwera Calendar MCP

Serwer Calendar MCP używa wskaźnika alokacji kosztów zapytań. W tabelach poniżej znajdziesz szczegółowe informacje o kosztach zapytań dla każdej metody serwera Calendar MCP według sekcji:

Limity Calendar MCP