Zasady dotyczące limitów

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Co

Za pomocą zasady dotyczącej limitu ustalisz liczbę wiadomości z żądaniem, które serwer proxy interfejsu API zezwala wysyłać w określonym przedziale czasu, np. w ciągu minuty, godziny, dnia, tygodnia lub miesiąca. Możesz ustawić ten limit na taki sam dla wszystkich aplikacji uzyskujących dostęp do proxy interfejsu API, albo możesz ustawić go na podstawie:

• Produkt, który zawiera serwer proxy interfejsu API
• Aplikacja wysyłająca żądanie do interfejsu API
• Deweloper aplikacji
• wiele innych kryteriów.

Nie używaj limitu do ochrony przed ogólnymi wzrostami ruchu. W tym celu użyj zasady Spike Arrest. Zapoznaj się z zasadami dotyczącymi zatrzymywania treści.

Filmy

Te filmy wprowadzają zarządzanie limitem na podstawie zasad dotyczących limitu:

Przykłady

Te przykłady kodu zasad pokazują, jak rozpoczynać i kończyć okresy limitu:

<Quota name="CheckQuota"> 
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

<Quota name="DeveloperQuota"> 
  <Identifier ref="verifyapikey.verify-api-key.client_id"/> 
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> 
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> 
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> 
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Identifier ref="request.queryparam.id"/>

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

Zasady dotyczące limitów

Limit to przydział wiadomości z prośbami, które serwer proxy interfejsu API może obsłużyć w określonym przedziale czasu, np. w ciągu minuty, godziny, dnia, tygodnia lub miesiąca. Zasady zawierają liczniki, które zliczają liczbę żądań otrzymanych przez serwer proxy interfejsu API. Ta funkcja umożliwia dostawcom interfejsów API nakładanie limitów na liczbę wywołań interfejsu API wykonywanych przez aplikacje w danym przedziale czasu. Za pomocą zasad dotyczących limitu możesz na przykład ograniczyć liczbę żądań wysyłanych przez aplikacje do 1 żądania na minutę lub 10 tys. żądań na miesiąc.

Jeśli na przykład limit wynosi 10 tys. wiadomości miesięcznie, ograniczanie szybkości rozpoczyna się po wysłaniu 10 tysięcznego wiadomości. Nie ma znaczenia,czy 10 tys. wiadomości zostało zliczonych pierwszego dnia czy ostatniego dnia tego okresu. Nie można wysyłać dodatkowych żądań, dopóki licznik limitu nie zostanie automatycznie zresetowany na koniec podanego przedziału czasu lub dopóki limit nie zostanie wyraźnie zresetowany za pomocą zasad resetowania limitu.

Różnica w przypadku limitu zwana SpikeArrest zapobiega nagłym wzrostom (lub skokom) natężenia ruchu, które mogą być spowodowane nagłym wzrostem wykorzystania, błędnymi klientami lub atakami złośliwymi. Więcej informacji o SpikeArrest znajdziesz w zasadach dotyczących SpikeArrest.

Limity dotyczą poszczególnych serwerów proxy interfejsu API i nie są rozkładane na nie. Jeśli np. masz 3 serwery proxy API w ramach usługi interfejsu API, jeden limit nie jest udostępniany wszystkim 3 serwerom, nawet jeśli wszystkie 3 serwery korzystają z tej samej konfiguracji zasady dotyczącej limitu.

Typy zasad dotyczących limitów

Zasady dotyczące limitów obsługują kilka różnych typów zasad: domyślne, calendar, flexi i rollingwindow. Każdy typ określa, kiedy licznik limitu zaczyna się odliczać i kiedy się resetuje, jak pokazano w tabeli poniżej:

W przypadku type="calendar" musisz podać wartość <StartTime>.

Tabela nie zawiera wartości typu rollingwindow. Okno kumulacyjne limity działają poprzez ustawienie rozmiaru „okna” limitu, np. 1 godziny lub 1 dnia. Gdy wpłynie nowe żądanie, zasady określają, czy w ostatnim „oknie” czasowym nie przekroczono limitu.

Możesz na przykład zdefiniować 2-godzinne okno, w którym dozwolisz na 1000 żądań. Nowe żądanie przychodzi o 16:45.Polityka oblicza limit na podstawie liczby żądań w ciągu ostatnich 2 godzin, czyli od 14:45. Jeśli w tym 2-godzinnym oknie nie przekroczysz limitu, żądanie zostanie zaakceptowane.

Minutę później, o 16:46, przychodzi kolejna prośba. Teraz zasada oblicza liczbę limitów od godziny 14:46, aby ustalić, czy limit został przekroczony.

W przypadku typu rollingwindow licznik nigdy się nie resetuje, ale jest ponownie obliczany przy każdym żądaniu.

Liczniki limitów

Domyślnie zasada dotycząca limitu korzysta z jednego licznika niezależnie od tego, ile razy jest ona wywoływana w interfejsie API. Nazwa licznika limitu jest tworzona na podstawie atrybutu name w regułach.

Na przykład tworzysz politykę dotyczącą limitu o nazwie MyQuotaPolicy z limitem 5 żądań i umieszczasz ją w wielu przepływach (przepływ A, B i C) w interfejsie proxy API. Chociaż jest używany w kilku przepływach danych, utrzymuje jeden licznik, który jest aktualizowany przez wszystkie wystąpienia zasad:

• Przepływ A jest wykonywany -> MyQuotaPolicy jest wykonywany i jego licznik = 1
• Wykonywanie przepływu B -> zasada MyQuotaPolicy jest wykonywana i jej licznik = 2
• Przepływ A jest wykonywany -> MyQuotaPolicy jest wykonywany, a jego licznik = 3.
• Przepływ C jest wykonywany -> MyQuotaPolicy jest wykonywany i jego licznik = 4
• Przepływ A jest wykonywany > MyQuotaPolicy jest wykonywany i jego licznik = 5

Kolejne żądanie do dowolnego z tych 3 przepływów jest odrzucane, ponieważ licznik limitu osiągnął swój limit.

Używanie tej samej polityki dotyczącej limitów w więcej niż 1 miejscu w przepływie zapory API, co może nieumyślnie spowodować wyczerpanie limitu szybciej niż się spodziewasz, to antywzorzec opisany w książce The Book of Apigee Edge Antipatterns (Książka o antywzorcach Apigee Edge).

Możesz też zdefiniować w serwerze proxy interfejsu API wiele zasad dotyczących limitów i stosować inną zasadę w każdej ścieżce. Każda polityka dotycząca limitu ma własny licznik oparty na atrybucie name tej polityki.

Możesz też użyć elementów <Class> lub <Identifier> w zasadzie dotyczącej limitu, aby zdefiniować w jednej zasadzie wiele unikalnych liczników. Dzięki tym elementom jedna zasada może utrzymywać różne liczniki na podstawie aplikacji wysyłającej żądanie, dewelopera aplikacji wysyłającego żądanie, identyfikatora klienta lub innego identyfikatora klienta itp. Więcej informacji o używaniu elementów <Class> lub <Identifier> znajdziesz w przykładach powyżej.

Notacja czasu

Wszystkie limity czasowe są ustawione na uniwersalny czas koordynowany (UTC).

Notacja czasu w przypadku limitu jest zgodna z międzynarodowym standardem ISO 8601.

Daty są definiowane jako rok, miesiąc i dzień w formacie YYYY-MM-DD. Na przykład 2015-02-04 oznacza 4 lutego 2015 r.

Godzina jest definiowana jako liczba godzin, minut i sekund w tym formacie: hours:minutes:seconds. Na przykład 23:59:59 oznacza czas 1 sekunda przed północą.

Pamiętaj, że do rozróżnienia 2 północy, które mogą być powiązane z 1 datą, dostępne są 2 notacje: 00:00:00 i 24:00:00. Dlatego 2015-02-04 24:00:00 ma tę samą datę i godzinę co 2015-02-05 00:00:00. Druga z nich jest zwykle preferowaną notacją.

Pobieranie ustawień limitu w ramach konfiguracji produktu interfejsu API

Limity limitów możesz ustawiać w konfiguracjach usług API. Te limity nie powodują automatycznego stosowania limitu. Zamiast tego możesz użyć ustawień limitu dla produktu w zasadach dotyczących limitu. Oto kilka zalet ustawienia limitu dla usługi na potrzeby zasad dotyczących limitów:

• Zasady dotyczące limitów mogą używać jednolitych ustawień we wszystkich serwerach proxy interfejsu API w danym interfejsie API.
• Możesz wprowadzać zmiany ustawień limitu w czasie wykonywania w przypadku usługi interfejsu API, a zasady dotyczące limitu, które odwołują się do tej wartości, będą automatycznie aktualizować wartości limitu.

Więcej informacji o używaniu ustawień limitu w usłudze interfejsu API znajdziesz w przykładzie „Dynamiczny limit” powyżej.

Informacje o konfigurowaniu usług interfejsu API z ograniczeniami dotyczącymi limitów znajdziesz w artykule Tworzenie usług interfejsu API.

Element referencyjny

Poniżej znajdziesz elementy i atrybuty, które możesz skonfigurować w ramach tej zasady. Pamiętaj, że niektóre kombinacje elementów wykluczają się wzajemnie lub nie są wymagane. Zapoznaj się ze wzorami dotyczącymi konkretnego zastosowania. Poniższe zmienne verifyapikey.VerifyAPIKey.apiproduct.* są domyślnie dostępne, gdy w żądaniu używana jest zasada weryfikacji klucza API o nazwie „VerifyAPIKey” do sprawdzania klucza API aplikacji. Wartości zmiennych pochodzą z ustawień limitu usługi interfejsu API, z którą powiązany jest klucz, zgodnie z opisem w artykule Pobieranie ustawień limitu z konfiguracji usługi interfejsu API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Atrybuty <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Te atrybuty są związane z tymi zasadami.

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Allow>

Określa limit liczby dla limitu. Jeśli licznik dla tej zasady osiągnie tę wartość, kolejne wywołania będą odrzucane, dopóki licznik się nie wyzeruje.

Poniżej znajdziesz 3 sposoby ustawienia elementu <Allow>:

<Allow count="2000"/> 

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

Jeśli określisz zarówno parametr count, jak i countRef, pierwszeństwo będzie miał parametr countRef. Jeśli countRef nie zostanie rozwiązany w czasie wykonywania kodu, zostanie użyta wartość count.

Atrybuty

Element <Allow>/<Class>

Element <Class> umożliwia warunkowe nadawanie wartości elementom <Allow> na podstawie wartości zmiennej przepływu. W przypadku każdego tagu podrzędnego <Allow> elementu <Class> zasada używa innego licznika.

Aby użyć elementu <Class>, wskaż zmienną przepływu, używając atrybutu ref w tagu <Class>. Następnie Edge używa wartości zmiennej przepływu, aby wybrać jeden z tagów podrzędnych <Allow>, który określi dozwoloną liczbę zasad. Edge dopasowuje wartość zmiennej przepływu do atrybutu class tagu <Allow>, jak pokazano poniżej:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

W tym przykładzie bieżący licznik limitu jest określany przez wartość parametru zapytania time_variable przekazywanego z każdym żądaniem. Ta zmienna może mieć wartość peak_time lub off_peak_time. Jeśli parametr zapytania zawiera nieprawidłową wartość, zasady zwracają błąd naruszenia limitu.

Atrybuty

<Allow>/<Class>/<Allow> element

Element <Allow> określa limit dla licznika limitu określonego przez element <Class>. W przypadku każdego innego tagu podrzędnego <Allow> elementu <Class> zasada utrzymuje inny licznik.

Na przykład:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

W tym przykładzie zasada dotycząca limitu korzysta z 2 liczników limitu o nazwach peak_time i off_peak_time.

Atrybuty

Element <Interval>

Użyj tego parametru, aby określić liczbę całkowitą (np. 1, 2, 5, 60 itd.), która zostanie połączona z określonym parametrem TimeUnit (minuty, godziny, dni, tygodnie lub miesiące), aby określić przedział czasu, w którym Edge oblicza wykorzystanie limitu.

Na przykład Interval 24 z TimeUnit hour oznacza, że limit zostanie obliczony w ciągu 24 godzin.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

Atrybuty

Element <TimeUnit>

Użyj tego pola, aby określić jednostkę czasu obowiązującą w przypadku limitu.

Na przykład Interval 24 z TimeUnit hour oznacza, że limit zostanie obliczony w ciągu 24 godzin.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Atrybuty

Element <StartTime>

Gdy wartość type jest ustawiona na calendar,, określa datę i godzinę, od której licznik limitu zacznie się odliczać, niezależnie od tego, czy aplikacje wysłały jakieś żądania.

Na przykład:

<StartTime>2017-7-16 12:00:00</StartTime>

Element <Distributed>

Instalacja przeglądarki Edge może używać co najmniej 1 procesora wiadomości do przetwarzania żądań. Ustaw ten element na true, aby określić, że zasada powinna utrzymywać centralny licznik i ciągle go synchronizować we wszystkich procesorach wiadomości. Przetwarzanie wiadomości może odbywać się w różnych strefach dostępności lub regionach.

Jeśli użyjesz wartości domyślnej false, możesz przekroczyć limit, ponieważ liczba dla każdego procesora wiadomości nie jest współdzielona:

<Distributed>true</Distributed>

Aby mieć pewność, że liczniki są synchronizowane i aktualizowane przy każdym żądaniu, ustaw wartości <Distributed> i <Synchronous> na prawda:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

Element <Synchronous>

Ustaw na true, aby zsynchronizować zliczanie rozproszonego limitu. Oznacza to, że zliczanie jest aktualizowane w tym samym czasie, gdy sprawdzany jest limit w żądaniu wysyłanym do interfejsu API. Ustaw na true, jeśli chcesz, aby żadne wywołania interfejsu API nie przekraczały limitu.

Aby zaktualizować licznik limitu asynchronicznie, ustaw wartość false. Oznacza to, że niektóre wywołania interfejsu API, które przekraczają limit, mogą być realizowane, w zależności od tego, kiedy licznik limitu w repozytorium centralnym jest aktualizowany asynchronicznie. Nie będziesz jednak mieć do czynienia z potencjalnymi problemami z wydajnością związanymi z aktualizacjami synchronicznymi.

Domyślny asynchroniczny interwał aktualizacji to 10 sekund. Aby skonfigurować to zachowanie asynchroniczne, użyj elementu AsynchronousConfiguration.

<Synchronous>false</Synchronous>

Element <AsynchronousConfiguration>

Konfiguruje interwał synchronizacji między rozłożonymi na wiele serwerów licznikami limitu, gdy element konfiguracji zasad <Synchronous> jest nieobecny lub obecny i ustawiony na false.

Synchronizację możesz wykonać po upływie określonego czasu lub po osiągnięciu określonej liczby wiadomości, używając elementów podrzędnych SyncIntervalInSeconds lub SyncMessageCount. Te opcje wzajemnie się wykluczają. Na przykład

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

lub

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Element <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Użyj tej opcji, aby zastąpić domyślne zachowanie, w którym asynchroniczne aktualizacje są wykonywane co 10 sekund.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

Interval synchronizacji musi wynosić co najmniej 10 sekund, zgodnie z opisem w artykule Limity.

<AsynchronousConfiguration>/<SyncMessageCount> element

Określa liczbę żądań w ramach wszystkich procesorów wiadomości Apigee między aktualizacjami limitu.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

W tym przykładzie określamy, że limit jest aktualizowany co 5 żądań w przypadku każdego procesora wiadomości Apigee Edge.

Element <Identifier>

Aby skonfigurować zasady w celu tworzenia unikalnych liczników na podstawie zmiennej przepływu, użyj elementu <Identifier>.

Jeśli nie używasz tego elementu, zasada używa jednego licznika, który jest stosowany w przypadku limitu.

Ten element jest również omawiany w tym poście w społeczności Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>

Atrybuty

Element <MessageWeight>

Użyj tego pola, aby określić wagę przypisaną do każdej wiadomości. Użyj wagi wiadomości, aby zwiększyć wpływ wiadomości żądania, które na przykład zużywa więcej zasobów obliczeniowych niż inne.

Możesz na przykład uznać, że żądania POST są dwa razy „cięższe” lub droższe niż żądania GET. Dlatego w przypadku metody POST ustawiasz wartość MessageWeight na 2, a w przypadku metody GET – na 1. Możesz nawet ustawić wartość parametru MessageWeight na 0, aby prośba nie wpływała na licznik. W tym przykładzie, jeśli limit wynosi 10 wiadomości na minutę, a MessageWeight dla żądań POST wynosi 2, limit będzie zezwalać na 5 żądań POST w dowolnym 10-minutowym interwale. Każde dodatkowe żądanie POST lub GET przed zresetowaniem licznika zostanie odrzucone.

Wartość reprezentująca MessageWeight musi być określona przez zmienną przepływu. Można ją wyodrębnić z nagłówków HTTP, parametrów zapytania, ładunku żądania XML lub JSON albo dowolnej innej zmiennej przepływu. Na przykład w nagłówku o nazwie weight:

<MessageWeight ref="message_weight"/>

Zmienne przepływu

Gdy zadziała reguła dotycząca limitu, automatycznie wypełnią się te wstępnie zdefiniowane zmienne przepływu: Więcej informacji o zmiennych w Flow znajdziesz w artykule Informacje o zmiennych.

Odniesienie do błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Zmienne błędów

Te zmienne są ustawiane, gdy ta zasada wywołuje błąd. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Przykładowa reguła błędu

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Schematy

Powiązane artykuły

Resetowanie zasad dotyczących limitu kwoty

SpikeArrest policy

Porównanie zasad dotyczących limitów, ograniczania dostępu w przypadku nagłego wzrostu ruchu i limitów współbieżnego dostępu