Przewodnik po limitach transakcji i częstotliwości

Firma FedEx codziennie otrzymuje wiele tysięcy żądań API. Stosujemy mechanizmy ograniczania przepustowości w celu zarządzania tak dużą liczbą żądań. Limity transakcji, limity częstotliwości i progi służą wydajnemu i skutecznemu przydzielaniu zasobów FedEx.

Limity transakcji definiuje się dla organizacji i dla projektu API.

Limity na organizację

Limit transakcji to maksymalna liczba żądań API, jakie można przesłać z danej organizacji w ciągu dnia. Oznacza to, że użytkownicy interfejsów API powinni wziąć pod uwagę łączną liczbę żądań API zainicjowanych dla wszystkich projektów w danej organizacji. Każde żądanie liczy się tak samo, niezależnie od objętości danych zwróconych w odpowiedzi interfejsu API firmy FedEx.

Przykład: Organizacja jest objęta limitem transakcji wynoszącym 500 000 żądań API na dzień. Jeżeli w ciągu pierwszych kilku godzin danego dnia organizacja prześle 500 000 żądań, osiągnie swój limit. Przez pozostałą część dnia, aż do kolejnego dnia, w odpowiedzi na każde żądanie zwrócony zostanie kod błędu „429 – Zbyt wiele żądań – przekroczono dzienny limit transakcji. Spróbuj ponownie po godzinie 12:00 GMT”.

Limity na projekt API

Ten limit jest stosowany na dwóch różnych poziomach: projektu i funkcji.

Jak należy rozumieć funkcje?

Każdy interfejs API jest grupowany na podstawie funkcji, jakie udostępnia. Każda grupa funkcji stanowi pakiet co najmniej jednego punktu końcowego. Na przykład funkcja interfejsu API śledzenia obejmuje 6 punktów końcowych interfejsu API, natomiast funkcja weryfikacji adresu obejmuje tylko 1 punkt końcowy interfejsu API.

Domyślny limit transakcji PCPP (ang. Per Capability Per Project) dla funkcji śledzenia wynosi 100 tys. żądań na dzień. Oznacza to, że gdy ruch z któregokolwiek z projektów w organizacji do któregokolwiek z 6 punktów końcowych w ramach funkcji śledzenia przekroczy ten limit, wówczas użytkownik będzie otrzymywał do końca dnia komunikat o błędzie „429 – Zbyt wiele żądań”. Odnosi się to do wszystkich kolejnych żądań śledzenia dla któregokolwiek z 6 punktów końcowych.

Przykład: Jeżeli projekt jest objęty limitem 100 tys. na funkcję śledzenia (przy 6 punktach końcowych), łączna liczba transakcji dla wszystkich 6 punktów końcowych zostanie uwzględniona w limicie 100 tysięcy. Jeżeli projekt przekroczy wskazany limit, wówczas w przypadku kolejnych transakcji śledzenia użytkownik będzie otrzymywał kod błędu „429 – Zbyt wiele żądań – przekroczono dzienny limit transakcji” przez pozostałą część dnia do godziny 12:00 GMT.

Limity częstotliwości

Każdy projekt jest objęty limitem częstotliwości transakcji wynoszącym 1400 transakcji w ciągu 10 sekund. Jeśli liczba transakcji przekroczy limit w dowolnym 10-sekundowym okresie, zastosowane zostaną ograniczenia przepustowości.

Jeśli limit ten zostanie osiągnięty w ciągu pierwszych kilku sekund, wówczas wszelkie transakcje przesłane w pozostałych sekundach tego 10-sekundowego okresu zostaną objęte ograniczeniami przepustowości. W okresie ograniczonej przepustowości zwracany będzie kod błędu „429 — zbyt wiele żądań”.

Jeśli firma FedEx otrzyma 1400 żądań w ciągu 2 pierwszych sekund, wówczas wszelkie kolejne transakcje zostaną ograniczone w ciągu kolejnych 8 sekund i wyświetli się komunikat o błędzie „429 – Zbyt wiele żądań – otrzymaliśmy zbyt wiele żądań w krótkim czasie. Zaczekaj chwilę i spróbuj ponownie”.

Po upływie 10 sekund ograniczenia przepustowości zostaną zniesione, a kolejny licznik zacznie śledzić liczbę żądań w ciągu następnych 10 sekund.

Progi

Progi są stosowane na poziomie adresu IP, aby proces autoryzacji interfejsów API firmy FedEx był odpowiednio odporny. Ten mechanizm dotyczy tylko usługi generowania tokena Auth. Istnieją dwa rodzaje progów:

1. Próg impulsu: 3 odsłony na sekundę, przez cały czas, w okresie trwającym 5 sekund
2. Próg średni: 1 odsłona na sekundę, przez cały czas, w okresie trwającym 2 minuty

• Gdy publiczny adres IP naruszy te limity progu, zostanie zablokowany na 10 minut, a wszystkie dalsze żądania w tym 10-minutowym okresie otrzymają kod statusu „403 – Dostęp zabroniony”.
• Jeśli konsumenci interfejsu API będą w dalszym ciągu naruszali limity progów w okresie kary, czas obowiązywania blokady zostanie wydłużony. Użytkownicy interfejsu API mogą zakończyć okres blokady poprzez nienaruszanie limitu progu przez kolejne 10 minut.
• Mechanizmy progu bazują na publicznym adresie IP użytkownika. Jeśli użytkownik skonfiguruje 10 instancji maszyn wirtualnych w ramach jednego publicznego adresu IP, wówczas wszystkie żądania z tego adresu IP będą wliczały się do limitu progu

Zarządzanie ruchem

Każdy z tych trzech mechanizmów odnosi się do innego aspektu zarządzania ruchem:

• Limity transakcji stosowane na poziomie organizacji: limitowi transakcji podlegał będzie łączny ruch wygenerowany przez wszystkie interfejsy API w organizacji.

• Limity transakcji stosowane na poziomie projektu: limitowi transakcji podlegał będzie ruch wygenerowany dla jednej funkcji interfejsu API w ramach projektu.

• Limity częstotliwości stosowane na poziomie projektu: limitowi częstotliwości podlegał będzie łączny ruch wygenerowany przez wszystkie interfejsy API w ramach projektu.

• Wartości progowe są stosowane na poziomie adresu IP.

Uwaga: Firma FedEx może zmniejszyć limity wspomnianych powyżej mechanizmów ograniczania przepustowości, aby zapobiegać niewłaściwemu wykorzystaniu, zbyt częstemu użytkowaniu i nadużywaniu. Firma FedEx zastrzega sobie prawo do zmiany przydziału bez wcześniejszego powiadomienia, aby utrzymać równomierny poziom dostępu wśród konsumentów interfejsu API i przydzielać zasoby FedEx w wydajny i skuteczny sposób.

Często zadawane pytania

Czy wszystkie transakcje API organizacji z różnych projektów wliczają się do limitu transakcji?
Limit transakcji jest stosowany na poziomie organizacji. W ramach jednej organizacji może istnieć jeden lub więcej projektów, a w ramach każdego projektu może istnieć jeden lub więcej interfejsów API. W rezultacie połączony ruch wygenerowany przez wszystkie interfejsy API z różnych projektów w ramach organizacji jest wliczany do codziennego limitu transakcji.

Jeśli ten sam błąd 429 jest zwracany w przypadku naruszenia limitu transakcji i naruszenia limitu częstotliwości, jak mogę zidentyfikować, do jakiego rodzaju naruszenia doszło?
Rodzaj naruszenia można zidentyfikować poprzez zapoznanie się z komunikatem o błędzie.

Jakie jest rozwiązanie związane z naruszeniem limitu progu?
Token OAuth jest ważny przez godzinę. Sugerujemy, aby konsumenci interfejsu API używali tego tokena przez całą godzinę, a następnie zażądali nowego tokena, gdy poprzedni wygaśnie.

Jak wygląda przykładowe przekroczenie limitu progu?
5 sekund i 2 minuty stanowią okresy obserwacyjne odpowiednio dla progu impulsu i progu średniego. Jeśli podczas każdego z tych okresów dowolny limit progu zostanie przekroczony z poziomu adresu IP, wówczas nakładana jest kara związana z progiem.

Przykład: Jeżeli adres IP miał 3 odsłony na sekundę przez 2 sekundy, po czym częstotliwość spadła poniżej 3 odsłon na sekundę, wówczas próg impulsu nie został naruszony. Jednak jeżeli adres IP miał 3 odsłony na sekundę przez cały czas w ciągu 5 sekund, a następnie 15 odsłon w ciągu 5 sekund, wówczas próg impulsu wynoszący 14 odsłon w ciągu 5 sekund został naruszony.