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 wziąć pod uwagę 3 ważne ograniczenia:

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: interfejs 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ą być stosowane w dowolnym momencie. Limity mogą na przykład obowiązywać, jeśli próbujesz szybko zapisywać dane w jednym kalendarzu.

Limity interfejsu Calendar API

Obowiązują 2 typy limitów:

Na minutę na projekt: liczba żądań, które Twój projekt w chmurze Google Cloud może wysłać w ciągu minuty.
Na minutę na użytkownika na projekt: liczba żądań, które może wysłać dowolny użytkownik w Twoim projekcie w chmurze. Ten limit pomaga zapewnić sprawiedliwy podział wykorzystania między użytkowników.

Limity są obliczane na minutę przy użyciu okna przesuwnego. Gwałtowny wzrost ruchu, który przekracza limit na minutę, powoduje 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 w chmurze 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 zostaną udostępnione w późniejszym okresie 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 i interfejsów API agenta.

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 przypadku aplikacji sieciowych. Algorytm wzrastającego czasu do ponowienia ponawia żądania, używając coraz dłuższych 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, 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ó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 wiele 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 Kalendarz Google API jest bezpłatne. Przekroczenie limitów żądań będzie wiązać się z obciążeniem Twojego konta rozliczeniowego Google Cloud w późniejszym okresie 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ę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 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 403 usageLimits kod stanu lub 429 usageLimits kod stanu.

W takim przypadku możesz 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 osiągnąć inne typy limitów, 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 gwałtowne wzrosty ruchu spowodowane wykonywaniem operacji przez wielu klientów w tym samym czasie. Na przykład częstym błędem w przypadku klienta Kalendarza jest przeprowadzanie pełnej synchronizacji o północy. Zwykle przekracza to limit na minutę i powoduje ograniczenie liczby żądań oraz wzrastający czas do ponowienia.

Aby tego uniknąć, w miarę możliwości rozłóż ruch 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ć jakąś operację, zmieniaj interwał o ±25%. Pozwala to równomiernie rozłożyć ruch i zwiększyć wygodę użytkowników.

Używanie powiadomień push

Częstym przypadkiem użycia jest wykonywanie działania, gdy coś się zmieni w kalendarzu użytkownika. Błędem jest w tym przypadku wielokrotne odpytywanie każdego interesującego kalendarza. Szybko wyczerpuje to 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, dzięki czemu Kalendarz może powiadamiać Cię o interesujących zdarzeniach. Wymaga to więcej pracy przy konfiguracji, ale pozwala efektywniej wykorzystywać limit i zwiększać wygodę użytkowników. Określ eventType, dla którego 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 limitami "na minutę na użytkownika na projekt", a nie użytkownik, którego reprezentujesz. Oznacza to, że konto usługi może wyczerpać limit i zostać objęte ograniczeniem liczby żądań, nawet jeśli działa na 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. Google używa tego parametru 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 prawidłowo obsługuje osiąganie limitów w praktyce (np. przez ponawianie prób ze wzrastającym czasem do ponowienia) i zminimalizować potencjalne zakłócenia dla użytkowników, przetestuj aplikację w realistycznym środowisku.

Aby przeprowadzić test bez zakłócania rzeczywistego korzystania z aplikacji, zarejestruj osobny projekt testowy w konsoli Google Cloud a następnie skonfiguruj ekran zgody OAuth w sposób podobny do projektu produkcyjnego. Następnie możesz ustawić sztucznie niskie limity limitów dla tego projektu i obserwować zachowanie aplikacji.

Limity serwera MCP Kalendarza

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

Limity MCP Kalendarza