Interfejs Google Calendar 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 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: 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 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 szybkości 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 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.
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 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 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 problemów z limitami opartymi na czasie
W przypadku wszystkich błędów opartych na czasie (maksymalnie N żądań na X minut) zalecamy aby kod przechwytywał wyjątek i używał obciętego 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 w sposób wykładniczy, 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_millisecondsi ponów żądanie. - Jeśli żądanie się nie powiedzie, odczekaj 2 +
random_number_millisecondsi ponów żądanie. - Jeśli żądanie się nie powiedzie, odczekaj 4 +
random_number_millisecondsi 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), anjest zwiększane o 1 w każdej iteracji (żądaniu). random_number_millisecondsto 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_millisecondsjest ponownie obliczana po każdym żądaniu ponowienia.maximum_backoffto 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ą już 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ększyłyby 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 może być konieczne zwiększenie wartości limitów. Jeśli przewidujesz znaczny wzrost wykorzystania w przyszłości, 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:
- Informacje o dostosowywaniu limitów
- Wyświetlanie wykorzystania limitów i limitów
- Wysyłanie prośby o wyższy limit
Rozwiązywanie problemów
Jeśli którykolwiek limit zostanie przekroczony, nastąpi ograniczenie szybkości 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 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, rozłóż obciążenie na 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 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 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 doprowadziłoby to do przekroczenia limitu na minutę i spowodowałoby ograniczanie 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%. Pozwoli to równomiernie rozłożyć ruch 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. Nieprawidłowym rozwiązaniem jest w tym przypadku wielokrotne sondowanie 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 sondowanie kalendarza każdego użytkownika odbywa się raz na minutę, wymaga to limitu na minutę wynoszącego co najmniej 5000, jeszcze zanim wykonasz jakąkolwiek pracę.
Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, dzięki czemu możemy Cię powiadamiać, gdy wydarzy się coś interesującego. Ich skonfigurowanie wymaga więcej pracy, ale pozwala na znacznie wydajniejsze wykorzystanie limitu i zapewnia 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 szybkości, 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 w praktyce prawidłowo obsługiwać osiąganie limitów (np. przez ponawianie prób z wzrastającym czasem do ponowienia ) 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. Możesz wtedy ustawić sztucznie niskie limity dla tego projektu i obserwować zachowanie aplikacji.