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 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.
- Limity operacyjne: w dowolnym momencie możesz zostać objęty ograniczeniem liczby żądań. Na przykład, gdy próbujesz szybko zapisać dane w jednym kalendarzu.
Rodzaje limitów wykorzystania interfejsu Calendar API
Obowiązują 2 rodzaje limitów:
- Na minutę na projekt: to liczba żądań wysłanych przez Twój projekt Google Cloud.
- Na minutę na projekt na użytkownika: to liczba żądań wysłanych przez dowolnego użytkownika w Twoim projekcie w Google Cloud. Ten limit ma pomóc w zapewnieniu sprawiedliwego rozkładu wykorzystania wśród użytkowników.
Limity są obliczane co minutę przy użyciu okna przesuwnego, więc nagły wzrost ruchu, który przekracza limit na minutę, spowoduje ograniczenie szybkości w następnym oknie, aby zapewnić, że średnie wykorzystanie pozostanie w granicach limitów.
Jeśli przekroczysz którykolwiek z tych limitów, usługa aktywuje ograniczanie liczby żądań i będziesz otrzymywać w odpowiedzi na zapytania 403 usageLimitskod stanu lub 429 usageLimitskod stanu. Jeśli tak się stanie, możesz wykonać te czynności:
- Pamiętaj, aby stosować wszystkie sprawdzone metody: używaj wycofywania wykładniczego, randomizuj 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 przydziału 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 generalnie nie zalecamy zwiększania go powyżej wartości domyślnej, ponieważ aplikacja może zacząć osiągać inne limity, np. 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:
- Jeśli nie masz jeszcze konta rozliczeniowego dla 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żytkowanie.
Używanie wzrastającego czasu do ponowienia
Gdy będziemy chcieli, aby zmniejszyć szybkość wysyłania żądań, zwrócimy odpowiedź 403 „usageLimits” lub odpowiedź 429 (patrz pełna dokumentacja błędów). Nie jest to błąd krytyczny. Oczekujemy, że po krótkiej przerwie ponowisz próbę wysłania żądania. Jeśli żądania nadal będą przychodzić zbyt szybko, ponownie poprosimy Cię o potwierdzenie, że nie jesteś robotem. Aby to działało prawidłowo, ważne jest, aby opóźnienia między żądaniami z czasem się zwiększały.
Zwykle należy używać obciętego wycofywania wykładniczego. W dokumentacji Cloud Storage znajdziesz dobre wyjaśnienie, jak to działa, oraz preferowany algorytm. Jeśli używasz biblioteki klienta Google, zwykle jest to obsługiwane automatycznie. Więcej informacji znajdziesz w dokumentacji biblioteki. Zwykle należy używać implementacji biblioteki zamiast pisać własną.
Losowe wzorce ruchu
Klienci Kalendarza są podatni na nagłe wzrosty ruchu spowodowane przez wielu klientów wykonujących operacje w tym samym czasie. Na przykład częstym błędem w przypadku klienta Kalendarza jest przeprowadzanie pełnej synchronizacji o północy. Prawie na pewno doprowadzi to do przekroczenia limitu minutowego i spowoduje ograniczenie szybkości oraz wycofanie.
Aby tego uniknąć, w miarę możliwości rozłóż ruch w ciągu dnia. Jeśli klient musi przeprowadzać codzienną synchronizację, powinien wybrać losową godzinę (inną dla każdego klienta). Jeśli musisz regularnie wykonywać jakąś operację, zmieniaj interwał o +/- 25%. Dzięki temu ruch będzie bardziej równomierny, a użytkownicy będą mogli wygodniej korzystać z witryny.
Korzystanie z powiadomień push
Częstym przypadkiem użycia jest wykonywanie działania, gdy coś się zmieni w kalendarzu użytkownika. Antywzorcem jest tutaj wielokrotne odpytywanie każdego kalendarza, który Cię interesuje. W ten sposób bardzo szybko wykorzystasz cały limit. Jeśli na przykład Twoja aplikacja ma 5000 użytkowników i co minutę odpytuje kalendarz każdego z nich, to nawet przed wykonaniem jakiejkolwiek pracy będzie potrzebny limit co najmniej 5000 zapytań na minutę.
Aplikacje po stronie serwera mogą rejestrować się w celu otrzymywania powiadomień push, co pozwala nam informować Cię o interesujących Cię wydarzeniach. Ich skonfigurowanie wymaga więcej pracy, ale pozwalają one znacznie efektywniej wykorzystywać limit i zapewniają lepsze wrażenia użytkownikom. Określ eventType, o których chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w sekcji Powiadomienia push.
Prawidłowe rozliczanie za pomocą kont usługi
Jeśli aplikacja wysyła żądania za pomocą przekazywania dostępu w całej domenie, domyślnie opłaty są naliczane na konto usługi w ramach limitów „na minutę na projekt na użytkownika”, a nie na użytkownika, którego tożsamość jest podszywana. 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 zostanie obciążony opłatą. Jest to używane tylko do obliczania limitów. Więcej informacji znajdziesz w sekcji Ograniczanie liczby żądań na użytkownika w dokumentacji Cloud.
Testowanie obsługi limitu
Aby mieć pewność, że aplikacja poradzi sobie z osiągnięciem limitów w praktyce (np. przez ponawianie prób z wykładniczym wycofywaniem) i zminimalizować potencjalne zakłócenia dla użytkowników, zdecydowanie zalecamy przetestowanie tego scenariusza w rzeczywistym środowisku.
Aby taki test nie zakłócał korzystania z prawdziwej aplikacji, zalecamy zarejestrowanie w Konsoli interfejsów API Google osobnego projektu przeznaczonego tylko do testów i skonfigurowanie go w sposób podobny do projektu produkcyjnego. Możesz wtedy ustawić sztucznie niskie limity dla tego projektu i obserwować zachowanie aplikacji.
Ceny
Korzystanie z interfejsu Google Calendar API jest bezpłatne. Przekroczenie limitów liczby żądań nie wiąże się z dodatkowymi opłatami, a Twoje konto nie zostanie obciążone.