Interfejs API Kalendarza Google ma limity, aby zapewnić sprawiedliwe korzystanie z niego przez wszystkich użytkowników. Podczas korzystania z interfejsu 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 następnej sekcji.
- Ogólne limity korzystania z Kalendarza: unikaj limitów korzystania z Kalendarza.
- Ograniczenia operacyjne: w dowolnym momencie możesz zostać objęty ograniczeniem stawek. Jeśli na przykład spróbujesz zapisać dane w jednym kalendarzu w krótkich odstępach czasowych.
Typy limitów interfejsu Calendar API
Stosowane są 2 typy limitów:
- Na minutę na projekt:liczba żądań wysłanych przez Twój projekt Google Cloud.
- Na minutę w danym projekcie na użytkownika: liczba żądań wysłanych przez dowolnego użytkownika w Twoim projekcie Cloud. Ten limit ma na celu zapewnienie sprawiedliwego rozłożenia wykorzystania między użytkowników.
Limity są obliczane co minutę za pomocą okna przesuwającego, więc nagły wzrost natężenia ruchu, który przekroczy limit minutowy w ciągu jednej minuty, spowoduje ograniczenie szybkości w następnym oknie, aby zapewnić, że średnio Twoje wykorzystanie pozostanie w ramach limitów.
Jeśli przekroczysz którykolwiek z tych limitów, zostaniesz objęty ograniczeniem szybkości i w przypadku Twoich zapytań otrzymasz kod stanu 403 usageLimits lub 429 usageLimits. W takim przypadku możesz:
- Pamiętaj o stosowaniu wszystkich sprawdzonych metod: używaj ujemnego wykładniczego współczynnika, losuj wzorce ruchu, 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 na projekt.
- Jeśli osiągniesz limit na użytkownika, możesz wykonać te czynności:
- Jeśli używasz konta usługi, przypisz obciążenie użytkownikom 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 ponad wartość domyślną, ponieważ aplikacja może zacząć przekraczać inne limity, na przykład ogólne limity korzystania z kalendarza lub limity operacyjne.
Prośba o zwiększenie limitu
Aby wyświetlić lub zmienić limity wykorzystania w projekcie albo poprosić o zwiększenie limitu, wykonaj te czynności:
- Jeśli nie masz jeszcze konta rozliczeniowego dla swojego projektu, utwórz je.
- Otwórz stronę „Włączone interfejsy API” w bibliotece interfejsów API w Konsoli interfejsów API i wybierz interfejs API z listy.
- Aby wyświetlić i zmienić ustawienia związane z limitami, kliknij Limity. Aby wyświetlić statystyki użytkowania, kliknij Użycie.
Używanie wzrastającego czasu do ponowienia
Jeśli chcemy, abyś zmniejszył częstotliwość wysyłania żądań, zwrócimy kod błędu 403 „usageLimits” lub kod 429 (patrz pełna dokumentacja błędów). Nie jest to błąd krytyczny, dlatego zalecamy ponowne przesłanie żądania po krótkiej chwili. Jeśli żądania nadal będą nadchodzić zbyt szybko, będziemy prosić o powtórzenie, itd. Aby to działało prawidłowo, ważne jest, aby opóźnienia między żądaniami zwiększały się z czasem.
Zazwyczaj należy używać odciętej ujemnej funkcji wykładniczej. W dokumentacji Cloud Storage znajdziesz dobre wyjaśnienie działania tego algorytmu i jego zalet. Jeśli używasz biblioteki klienta Google, zwykle nie musisz nic robić. Zapoznaj się z dokumentacją biblioteki. Zwykle należy używać implementacji biblioteki zamiast pisać własną.
Losowanie wzorców ruchu
W przypadku klientów kalendarza występują gwałtowne zmiany w wzorze ruchu spowodowane tym, że wiele klientów wykonuje operacje w tym samym czasie. Na przykład częstym błędem popełnianym przez klientów aplikacji Kalendarz jest przeprowadzanie pełnej synchronizacji o północy. Prawie na pewno spowoduje to przekroczenie limitu na minutę i spowoduje ograniczenie szybkości przesyłania danych oraz wycofanie się.
Aby tego uniknąć, staraj się rozłożyć ruch na cały dzień. Jeśli klient musi przeprowadzać codzienną synchronizację, poproś go o określenie losowego czasu (różnego dla każdego klienta). Jeśli operacja ma być wykonywana regularnie, zmieniaj interwał o +/-25%. Dzięki temu ruch będzie rozłożony bardziej równomiernie, a użytkownicy będą mogli wygodniej korzystać z usługi.
Korzystanie z powiadomień push
Typowym przypadkiem użycia jest wykonanie działania, gdy w kalendarzu użytkownika nastąpi zmiana. Nie zalecamy wielokrotnego sprawdzania każdego kalendarza. Bardzo szybko wyczerpie to całą Twoją pulę. Jeśli na przykład Twoja aplikacja ma 5000 użytkowników i każdy z nich sprawdza kalendarz raz na minutę, będzie to wymagać co najmniej 5000 minut na minutę, zanim aplikacja wykona jakiekolwiek działanie.
Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, co pozwala nam informować Cię o wydarzeniach, które mogą Cię zainteresować. Ich konfiguracja wymaga więcej pracy, ale pozwala znacznie efektywniej korzystać z limitu i zapewnia większą wygodę użytkowników. Pamiętaj, aby określić eventType, o których chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w artykule Powiadomienia push.
Prawidłowe rozliczanie 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 zgodnie z kwotami „na minutę na projekt na użytkownika”, a nie zgodnie z użytkownikiem, którego wcielasz się w jego rolę. Oznacza to, że konto usługi prawdopodobnie przekroczy limit i będzie ograniczone pod względem szybkości, mimo że może działać na wielu kalendarzach użytkowników. Aby tego uniknąć, użyj parametru quotaUser w adresie URL (lub nagłówka HTTP x-goog-quota-user), aby wskazać, któremu użytkownikowi zostanie naliczona opłata. Jest on używany tylko do obliczania limitów. Więcej informacji znajdziesz w dokumentacji Cloud na temat ograniczania liczby żądań na użytkownika.
Testowanie obsługi limitu
Aby mieć pewność, że Twoja aplikacja będzie mogła prawidłowo obsługiwać osiągnięcie limitów kwoty (np. przez powtarzanie prób z wykładniczym opóźnieniem) i minimalizować potencjalne zakłócenia dla użytkowników, zdecydowanie zalecamy przetestowanie tego scenariusza w rzeczywistym środowisku.
Aby taki test nie zakłócał korzystania z rzeczywistej aplikacji, zalecamy zarejestrowanie w Konsoli interfejsów API Google osobnego projektu tylko do testów i skonfigurowanie go w sposób podobny do projektu produkcyjnego. Następnie możesz ustawić sztucznie niskie limity dla tego projektu i obserwować zachowanie aplikacji.
Ceny
Korzystanie z interfejsu Google Calendar API jest bezpłatne. Przekroczenie limitu próśb o przekroczenie limitu nie powoduje dodatkowych opłat, a Twoje konto nie zostanie obciążone.