Zasady dotyczące limitów

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Za pomocą zasady Quota możesz skonfigurować liczbę wiadomości z żądaniami, które serwer proxy interfejsu API może przetwarzać w określonym czasie, np. w ciągu minuty, godziny, dnia, tygodnia lub miesiąca. Możesz ustawić ten sam limit dla wszystkich aplikacji uzyskujących dostęp do serwera proxy interfejsu API lub ustawić limit na podstawie:

• Produkt zawierający serwer proxy interfejsu API
• aplikacja, która wysyła żądanie do interfejsu API;
• Deweloper aplikacji
• wiele innych kryteriów.

Nie używaj limitu, aby chronić się przed ogólnymi skokami ruchu. Do tego celu użyj zasady Spike Arrest. Zapoznaj się z zasadami Spike Arrest.

Filmy

W tych filmach przedstawiamy zarządzanie limitami za pomocą zasad dotyczących limitów:

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>

Informacje o zasadach dotyczących limitów

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

Jeśli na przykład limit wynosi 10 tys. wiadomości miesięcznie, ograniczenie szybkości zaczyna się po wysłaniu 10-tysięcznej wiadomości. Nie ma znaczenia, czy 10 000 wiadomości zostało zliczonych pierwszego czy ostatniego dnia tego okresu. Do momentu automatycznego zresetowania licznika limitu na koniec określonego przedziału czasu lub do momentu wyraźnego zresetowania limitu za pomocą zasad resetowania limitu nie są dozwolone żadne dodatkowe żądania.

Odmiana limitu o nazwie SpikeArrest zapobiega nagłym wzrostom ruchu, które mogą być spowodowane nagłym wzrostem wykorzystania, błędami w klientach lub złośliwymi atakami. Więcej informacji o zasadach SpikeArrest znajdziesz w zasadach SpikeArrest.

Limity dotyczą poszczególnych serwerów proxy interfejsu API i nie są rozdzielane między serwery proxy interfejsu API. Jeśli na przykład produkt API zawiera 3 proxy interfejsu API, pojedynczy limit nie jest współdzielony przez wszystkie 3 proxy, nawet jeśli wszystkie 3 używają tej samej konfiguracji zasad 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 działać i kiedy jest resetowany, co pokazano w tej tabeli:

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

Tabela nie zawiera wartości typu rollingwindow. Limity w oknie ruchomym działają na zasadzie ustawienia rozmiaru „okna” limitu, np. okna godzinnego lub dziennego. Gdy nadejdzie nowe żądanie, zasady określą, czy w przeszłości w określonym „oknie” czasowym limit został przekroczony.

Możesz na przykład zdefiniować 2-godzinny okres, w którym można wysłać 1000 żądań. O godzinie 16:45 przychodzi nowe żądanie.Zasady obliczają limit na podstawie liczby żądań z ostatnich 2 godzin, czyli od 14:45. Jeśli w tym 2-godzinnym okresie limit przydziału nie został przekroczony, żądanie jest dozwolone.

Minutę później, o 16:46, pojawia się kolejna prośba. Teraz zasady obliczają liczbę limitów od godziny 14:46, aby sprawdzić, czy limit został przekroczony.

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

Informacje o licznikach limitów

Domyślnie zasada Quota utrzymuje jeden licznik, niezależnie od tego, ile razy odwołujesz się do niej w proxy interfejsu API. Nazwa licznika limitu zależy od atrybutu name zasad.

Załóżmy, że tworzysz zasadę dotyczącą limitu o nazwie MyQuotaPolicy z limitem 5 żądań i umieszczasz ją w kilku przepływach (A, B i C) w proxy interfejsu API. Mimo że jest używana w wielu procesach, ma jeden licznik, który jest aktualizowany przez wszystkie instancje zasady:

• Wykonanie przepływu A -> Wykonanie zasady MyQuotaPolicy, a jej licznik = 1
• Wykonanie przepływu B -> Wykonanie zasady MyQuotaPolicy, a jej licznik = 2
• Wykonanie przepływu A -> wykonanie zasady MyQuotaPolicy, a jej licznik = 3
• Wykonany zostaje przepływ C -> wykonana zostaje zasada MyQuotaPolicy, a jej licznik ma wartość 4.
• Wykonanie przepływu A -> wykonanie zasady MyQuotaPolicy, a jej licznik = 5

Kolejne żądanie do dowolnego z tych 3 procesów zostanie odrzucone, ponieważ licznik limitu osiągnął swój limit.

Używanie tej samej zasady dotyczącej limitów w więcej niż 1 miejscu w przepływie serwera proxy interfejsu API może nieumyślnie spowodować szybsze wyczerpanie limitu niż oczekiwano. Jest to anty-wzorzec opisany w książce „The Book of Apigee Edge Antipatterns”.

Możesz też zdefiniować w proxy interfejsu API kilka zasad dotyczących limitów i używać różnych zasad w każdym przepływie. Każda zasada dotycząca limitu ma własny licznik oparty na atrybucie name zasady.

Możesz też użyć elementów <Class> lub <Identifier> w zasadach dotyczących limitów, aby zdefiniować w jednych zasadach wiele unikalnych liczników. Dzięki tym elementom pojedyncze zasady mogą 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> i <Identifier> znajdziesz w przykładach powyżej.

Notacja czasu

Wszystkie godziny limitu są ustawione w strefie czasowej uniwersalnego czasu koordynowanego (UTC).

Notacja czasu przydziału jest zgodna z międzynarodowym standardem notacji daty określonym w normie ISO 8601.

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

Godzina jest określana w formacie hours:minutes:seconds. Na przykład 23:59:59 oznacza godzinę o sekundę przed północą.

Pamiętaj, że dostępne są 2 notacje: 00:00:00 i 24:00:00, które pozwalają odróżnić 2 północe, które mogą być powiązane z jedną datą. Dlatego 2015-02-04 24:00:00 to ta sama data i godzina co 2015-02-05 00:00:00. Zwykle preferowany jest ten drugi zapis.

Pobieranie ustawień limitu z konfiguracji produktu API

Limity możesz ustawić w konfiguracjach produktów interfejsu API. Limity te nie wymuszają automatycznie limitu. Zamiast tego możesz odwołać się do ustawień limitu produktu w zasadach dotyczących limitów. Oto niektóre zalety ustawienia limitu produktu, do którego będą się odwoływać zasady dotyczące limitów:

• Zasady dotyczące limitów mogą używać jednolitego ustawienia we wszystkich serwerach proxy interfejsu API w produkcie API.
• Możesz wprowadzać zmiany w ustawieniu limitu w produkcie interfejsu API w czasie działania, a zasady limitów, które odwołują się do tej wartości, będą automatycznie aktualizować wartości limitów.

Więcej informacji o korzystaniu z ustawień limitów w produkcie interfejsu API znajdziesz w przykładzie „Dynamiczne limity” powyżej..

Informacje o konfigurowaniu produktów interfejsu API z limitami wykorzystania znajdziesz w artykule Tworzenie produktów interfejsu API.

Odwołanie do elementu

Poniżej znajdziesz elementy i atrybuty, które możesz skonfigurować w tych zasadach. Pamiętaj, że niektóre kombinacje elementów wykluczają się wzajemnie lub nie są wymagane. Przykłady konkretnych zastosowań znajdziesz w próbkach. Poniższe zmienne verifyapikey.VerifyAPIKey.apiproduct.* są dostępne domyślnie, gdy do sprawdzenia klucza interfejsu API aplikacji w żądaniu używana jest zasada weryfikacji klucza interfejsu API o nazwie „VerifyAPIKey”. Wartości zmiennych pochodzą z ustawień limitu w usłudze API, z którą jest powiązany klucz, zgodnie z opisem w sekcji Pobieranie ustawień limitu z konfiguracji usługi 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">

Poniższe atrybuty są specyficzne dla tych zasad.

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 zasady osiągnie tę wartość, kolejne wywołania są odrzucane do momentu zresetowania licznika.

Poniżej przedstawiamy 3 sposoby ustawiania 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 rozpoznane w czasie działania, użyta zostanie wartość count.

Atrybuty

Element <Allow>/<Class>

Element <Class> umożliwia warunkowe określanie wartości elementu <Allow> na podstawie wartości zmiennej przepływu. W przypadku każdego innego tagu podrzędnego <Allow> tagu <Class> zasady utrzymują inny licznik.

Aby użyć elementu <Class>, określ zmienną przepływu za pomocą atrybutu ref w tagu <Class>. Edge używa wartości zmiennej przepływu, aby wybrać jeden z <Allow>tagów podrzędnych i 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. Zmienna może mieć wartość peak_time lub off_peak_time. Jeśli parametr zapytania zawiera nieprawidłową wartość, zasady zwracają błąd przekroczenia limitu.

Atrybuty

Element <Allow>/<Class>/<Allow>

Element <Allow> określa limit licznika limitu zdefiniowanego przez element <Class>. W przypadku każdego innego tagu podrzędnego <Allow> tagu <Class> zasady utrzymują 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 utrzymuje 2 liczniki limitów o nazwach peak_time i off_peak_time.

Atrybuty

Element <Interval>

Użyj, aby określić liczbę całkowitą (np. 1, 2, 5, 60 itd.), która będzie powiązana z określonym przez Ciebie TimeUnit (minuta, godzina, dzień, tydzień lub miesiąc) w celu określenia przedziału czasu, w którym Edge oblicza wykorzystanie limitu.

Na przykład Interval wynoszący 24 z TimeUnit wynoszącym 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 tej opcji, aby określić jednostkę czasu, do której odnosi się limit.

Na przykład Interval wynoszący 24 z TimeUnit wynoszącym 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 parametr type ma wartość calendar,, określa datę i godzinę, od których licznik limitu zacznie zliczać żądania, niezależnie od tego, czy z jakichkolwiek aplikacji wpłynęły jakieś żądania.

Na przykład:

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

Element <Distributed>

Instalacja Edge może używać co najmniej 1 procesora wiadomości do przetwarzania żądań. Ustaw ten element na true, aby określić, że zasady mają utrzymywać centralny licznik i stale synchronizować go na wszystkich procesorach wiadomości. Procesory wiadomości mogą znajdować 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 każdego procesora wiadomości nie jest udostępniana:

<Distributed>true</Distributed>

Aby zagwarantować, że liczniki są zsynchronizowane i aktualizowane przy każdym żądaniu, ustaw wartości <Distributed> i <Synchronous> na „true”:

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

Element <Synchronous>

Ustaw wartość true, aby synchronicznie zaktualizować licznik limitu rozproszonego. Oznacza to, że aktualizacja licznika następuje w tym samym czasie, w którym sprawdzany jest limit w żądaniu wysyłanym do interfejsu API. Ustaw wartość true, jeśli nie chcesz zezwalać na żadne wywołania interfejsu API przekraczające limit.

Ustaw wartość false, aby zaktualizować licznik limitu asynchronicznie. Oznacza to, że niektóre wywołania interfejsu API przekraczające limit mogą zostać zrealizowane w zależności od tego, kiedy licznik limitu w centralnym repozytorium zostanie zaktualizowany asynchronicznie. Nie będziesz jednak odczuwać potencjalnego wpływu na wydajność związanego z aktualizacjami synchronicznymi.

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

<Synchronous>false</Synchronous>

Element <AsynchronousConfiguration>

Konfiguruje interwał synchronizacji między rozproszonymi licznikami limitów, gdy element konfiguracji zasady <Synchronous> nie występuje lub występuje i ma wartość false.

Synchronizację możesz przeprowadzić 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. Wykluczają się one wzajemnie. 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 aktualizacje asynchroniczne są wykonywane po upływie 10 sekund.

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

Odstęp czasu synchronizacji musi wynosić co najmniej 10 sekund, zgodnie z opisem w temacie Limity.

Element <AsynchronousConfiguration>/<SyncMessageCount>

Określa liczbę żądań we wszystkich procesorach wiadomości Apigee między aktualizacjami limitu.

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

Ten przykład określa, że liczba limitów jest aktualizowana co 5 żądań w każdym procesorze wiadomości Apigee Edge.

Element <Identifier>

Użyj elementu <Identifier>, aby skonfigurować zasadę tworzenia unikalnych liczników na podstawie zmiennej przepływu.

Jeśli nie użyjesz tego elementu, zasady będą korzystać z jednego licznika, który będzie stosowany do limitu.

Ten element jest też omówiony w tym poście na forum społeczności Apigee: Identyfikator limitu w różnych zasadach.

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

Atrybuty

Element <MessageWeight>

Użyj, aby określić wagę przypisaną do każdej wiadomości. Używaj wagi wiadomości, aby zwiększyć wpływ wiadomości z prośbami, które np. zużywają więcej zasobów obliczeniowych niż inne.

Na przykład chcesz, aby wiadomości POST były 2 razy bardziej „obciążające” lub droższe niż wiadomości GET. Dlatego w przypadku metody POST ustawiasz wartość MessageWeight na 2, a w przypadku metody GET – na 1. Możesz nawet ustawić wartość MessageWeight na 0, aby żądanie nie miało wpływu na licznik. W tym przykładzie, jeśli limit wynosi 10 wiadomości na minutę, a MessageWeight dla żądań POST to 2, limit zezwala na 5 żądań POST w dowolnym 10-minutowym przedziale czasu. Wszelkie dodatkowe żądania POST lub GET przed zresetowaniem licznika zostaną odrzucone.

Wartość reprezentującą MessageWeight musi być określona przez zmienną przepływu i może być wyodrębniona z nagłówków HTTP, parametrów zapytania, ładunku żądania XML lub JSON albo dowolnej innej zmiennej przepływu. Możesz na przykład ustawić go w nagłówku o nazwie weight:

<MessageWeight ref="message_weight"/>

Zmienne przepływu

Gdy zasada dotycząca limitu zostanie wykonana, automatycznie wypełnią się te wstępnie zdefiniowane zmienne Flow: Więcej informacji o zmiennych przepływu znajdziesz w dokumentacji zmiennych.

Odniesienie do błędu

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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

Zasady ResetQuota

Zasady SpikeArrest

Porównanie zasad dotyczących limitów, ochrony przed nagłymi wzrostami i jednoczesnych limitów szybkości