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 Google Calendar API ma limity, które zapewniają, że wszyscy użytkownicy korzystają z niego w sposób uczciwy. Podczas korzystania z Calendar API należy wziąć pod uwagę 3 ważne ograniczenia:

Limity wykorzystania interfejsu API: są egzekwowane na poziomie projektu i użytkownika. Więcej informacji znajdziesz w artykule Typy limitów wykorzystania interfejsu Calendar API.
Ogólne limity wykorzystania Kalendarza Google: interfejs Google Calendar API to usługa udostępniana, 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ć ograniczone w dowolnym momencie. Na przykład jeśli spróbujesz zapisać dane w jednym kalendarzu w krótkich odstępach czasu.

Limity interfejsu Calendar API

Egzekwowane są 2 rodzaje limitów:

Na minutę na projekt: to liczba żądań, które projekt w chmurze Google może wysłać w ciągu minuty.
Na minutę na użytkownika na projekt: to liczba żądań, które dany użytkownik może wysłać w Twoim projekcie w chmurze. Ten limit ma pomóc w zapewnieniu sprawiedliwego podziału wykorzystania między użytkowników.

Limity są obliczane na minutę przy użyciu okna przesuwnego. Gwałtowny wzrost natężenia ruchu, który przekroczy limit na minutę w ciągu jednej minuty, spowoduje ograniczenie liczby żądań w następnym oknie, aby średnie wykorzystanie nie przekraczało limitów.

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

Typ limitu wykorzystania	Limit
Na minutę na projekt	10 000 żą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.

Użycie poniżej tego progu nie powoduje naliczenia dodatkowych opłat, a Twoje konto Google Cloud nie jest obciążane. Pełne informacje o płatnościach zostaną udostępnione w 2026 r. z co najmniej 90-dniowym wyprzedzeniem przed wejściem w życie jakichkolwiek 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	1 000 000 żądań

Więcej informacji znajdziesz w artykule Standaryzowany model Google Workspace dotyczący narzędzi i interfejsów API agentów.

Rozwiązywanie problemów 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, stosując wykładniczo rosnące czasy oczekiwania między żądaniami, aż do osiągnięcia maksymalnego czasu do ponowienia. Jeśli żądania nadal nie będą się udawać, ważne jest, aby opóźnienia między żądaniami zwiększały się z czasem, aż żądanie zostanie zrealizowane.

Przykładowy algorytm

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

wysyłać żą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, odczekaj 2 + random_number_milliseconds i spróbuj ponownie.
Jeśli żądanie 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 maksymalnej liczby prób, ale nie zwiększaj czasu oczekiwania między próbami.

gdzie:

Czas oczekiwania wynosi min(((2^n)+random_number_milliseconds), maximum_backoff), przy czym 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órej wielu klientów jest synchronizowanych 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.
Wartość maximum_backoff to zwykle 32 lub 64 sekundy. Odpowiednia wartość zależy od przypadku użycia.

Klient może kontynuować próby po upływie czasu maximum_backoff. Po tym czasie nie trzeba już zwiększać czasu oczekiwania. 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 próbami i liczba prób zależą od przypadku użycia i warunków sieciowych.

Ceny

Standardowe korzystanie z interfejsu Kalendarza Google API jest 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 Standaryzowany model Google Workspace dotyczący narzędzi i interfejsów API agentów.

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 użycie jednego konta. Wysłanie wniosku o zwiększenie limitu nie gwarantuje jego zatwierdzenia. Zatwierdzenie próśb o dostosowanie limitu, które znacznie zwiększyłyby wartość limitu, może potrwać dłużej.

Nie wszystkie projekty mają takie same limity. W miarę jak z czasem będziesz coraz częściej korzystać z Google Cloud, może być konieczne zwiększenie wartości limitów. 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 limitów, liczba żądań zostanie ograniczona, a 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 wzrastającego czasu do ponowienia, 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 ogólnie nie zalecamy zwiększania go powyżej wartości domyślnej, ponieważ aplikacja może zacząć przekraczać inne rodzaje limitów, np. ogólne limity wykorzystania kalendarza lub limity operacyjne.
Przetestuj limity, rejestrując osobny projekt testowy o konfiguracji podobnej do projektu produkcyjnego. Więcej informacji znajdziesz w artykule na temat testowania obsługi limitów.

Losowe wzorce ruchu

Klienci Kalendarza są podatni na gwałtowne wzrosty natężenia ruchu spowodowane przez wielu klientów wykonujących operacje 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 doprowadzi to do przekroczenia limitu na minutę i spowoduje ograniczenie liczby żądań oraz wycofanie.

Aby tego uniknąć, zadbaj o to, aby ruch był rozłożony w ciągu dnia, jeśli to możliwe. Jeśli klient musi przeprowadzać codzienną synchronizację, poproś go o wybranie losowej godziny (innej dla każdego klienta). Jeśli musisz wykonywać operację regularnie, zmieniaj interwał o +/- 25%. Dzięki temu ruch będzie rozłożony bardziej równomiernie, a użytkownicy będą mieli lepsze wrażenia.

Używanie powiadomień push

Typowym przypadkiem użycia jest wykonanie działania, gdy coś się zmieni w kalendarzu użytkownika. Antywzorcem jest tu wielokrotne odpytywanie każdego interesującego kalendarza. Spowoduje to bardzo szybkie wykorzystanie całego limitu. Jeśli na przykład Twoja aplikacja ma 5000 użytkowników i odpytuje kalendarz każdego z nich raz na minutę, wymaga to limitu na minutę wynoszącego co najmniej 5000, zanim jeszcze zostanie wykonana jakakolwiek praca.

Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, dzięki czemu możemy powiadamiać Cię, gdy wydarzy się coś interesującego. Wymagają one więcej pracy przy konfiguracji, ale pozwalają na znacznie efektywniejsze wykorzystanie limitu i zapewniają lepsze wrażenia użytkownikom. Pamiętaj, aby określić eventType, o których chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w artykule o powiadomieniach push.

Prawidłowe przydzielanie za pomocą kont usługi

Jeśli Twoja aplikacja wysyła żądania przy użyciu przekazywania dostępu w całej domenie, domyślnie konto usługi jest obciążane w ramach limitów „na minutę na użytkownika na projekt”, a nie użytkownik, pod którego się podszywasz. Oznacza to, że konto usługi prawdopodobnie wyczerpie limit i zostanie objęte ograniczeniem liczby żądań, mimo że może działać na kalendarzach wielu użytkowników.

Możesz tego uniknąć, używając parametru adresu URL quotaUser (lub nagłówka HTTP x-goog-quota-user), aby określić dowolny ciąg znaków (do 40 znaków), który jednoznacznie identyfikuje każdego użytkownika. Interfejs Calendar API używa tej wartości tylko do obliczania limitów.

Aby używać quotaUser do wymuszania limitów liczby żądań na użytkownika, żądania muszą spełniać te wymagania:

Dołącz klucz interfejsu API z ograniczeniem IP: przekaż klucz interfejsu API w parametrze zapytania key i skonfiguruj ten klucz z ograniczeniami adresów IP, określając publiczne adresy IP serwerów backendu. Jeśli pominiesz klucz interfejsu API lub nie skonfigurujesz ograniczeń adresów IP, interfejs Calendar API zignoruje parametr quotaUser i obciąży limitem uwierzytelnione konto (np. konto usługi).
Pomiń nagłówek X-Goog-User-Project: nie wysyłaj nagłówka HTTP X-Goog-User-Project w żądaniach, które używają quotaUser. Podanie projektu użytkownika zastępuje klucz interfejsu API na potrzeby przypisywania limitu, więc interfejs Calendar API ignoruje quotaUser.

Więcej informacji znajdziesz w artykule Ograniczanie liczby żądań na użytkownika.

Testowanie obsługi limitów

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

Aby przeprowadzić testy 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. Następnie możesz ustawić sztucznie niskie limity przydziału dla tego projektu i obserwować zachowanie aplikacji.

Limity serwera MCP Kalendarza

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

Limity MCP Kalendarza