Zasady dotyczące limitów

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

Co

Za pomocą zasady Quota możesz skonfigurować liczbę wiadomości z żądaniami, na które zezwala serwer proxy interfejsu API w określonym przedziale czasu, 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:

• Usługa zawierająca 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 dotyczącymi ochrony przed nagłymi wzrostami.

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 limitów, wykonując te czynności:

<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ń aplikacji do 1 na minutę lub 10 tys. na miesiąc.

Jeśli np. 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 klientów lub złośliwymi atakami. Więcej informacji o zasadach SpikeArrest znajdziesz w zasadach dotyczących ochrony przed nagłymi wzrostami ruchu.

Limity dotyczą poszczególnych proxy interfejsów API i nie są rozdzielane między nimi. Jeśli na przykład produkt API zawiera 3 proxy interfejsów API, pojedynczy limit nie jest współdzielony przez wszystkie 3 proxy, nawet jeśli wszystkie 3 używają tej samej konfiguracji zasady 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. Pokazuje to tabela poniżej:

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

Tabela nie zawiera wartości typu rollingwindow. Limity okna cyklicznego działają poprzez ustawienie rozmiaru „okna” limitu, np. okna godzinnego lub dziennego. Gdy nadejdzie nowe żądanie, zasady określają, 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ń. Nowe żądanie wpływa o 16:45.Zasady obliczają liczbę żądań w ciągu ostatnich 2 godzin, czyli liczbę żądań od 14:45. Jeśli w tym dwugodzinnym przedziale czasowym limit 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 zasady dotyczące limitu utrzymują jeden licznik, niezależnie od tego, ile razy odwołujesz się do nich w proxy interfejsu API. Nazwa licznika limitu zależy od atrybutu name zasad.

Załóżmy, że tworzysz zasadę dotyczącą limitów 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 limitu w więcej niż 1 miejscu w przepływie proxy interfejsu API, co może nieumyślnie spowodować szybsze wyczerpanie limitu niż oczekiwano, jest anty-wzorcem opisanym 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 utrzymuje własny licznik na podstawie atrybutu name zasady.

Możesz też użyć elementów <Class> lub <Identifier> w zasadach dotyczących limitów, aby zdefiniować wiele unikalnych liczników w jednych zasadach. Dzięki tym elementom pojedyncze zasady mogą utrzymywać różne liczniki w zależności od 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 na strefę czasową 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 czas na 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 usług API. Limity te nie wymuszają automatycznie limitu. Zamiast tego możesz odwołać się do ustawień limitu usługi 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 limitów mogą używać jednolitego ustawienia we wszystkich proxy interfejsów 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ń limitu z produktu interfejsu API znajdziesz w przykładzie „Dynamiczny limit” 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 ramach tych zasad. 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 Verify API Key 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 będą 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 count, jak i countRef, pierwszeństwo ma parametr countRef. Jeśli countRef nie zostanie rozpoznane w czasie działania, zostanie użyta 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 następnie 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ść, zasada zwraca błąd naruszenia 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 nieprzerwanie 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 procesorów komunikatów 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 rozproszonego limitu. 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 musisz się jednak obawiać potencjalnego wpływu na wydajność związanego z aktualizacjami synchronicznymi.

Domyślny interwał aktualizacji asynchronicznej to 10 sekund. Aby skonfigurować to działanie 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 tego ustawienia, aby zastąpić domyślne działanie, 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 limitu jest aktualizowana co 5 żądań w każdym procesorze wiadomości Apigee Edge.

Element <Identifier>

Użyj elementu <Identifier>, aby skonfigurować zasady 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 również omówiony w tym poście na forum społeczności Apigee: Quota identifier across different policies (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żyj wagi wiadomości, aby zwiększyć wpływ wiadomości z prośbą, które np. zużywają więcej zasobów obliczeniowych niż inne.

Na przykład chcesz, aby wiadomości POST były 2 razy „cięższe” 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 są odrzucane.

Wartość reprezentująca 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 Flow znajdziesz w dokumentacji zmiennych.

Odwołanie 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

Zasady ResetQuota

Zasady SpikeArrest

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