Kontingentrichtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Übersicht

Ein Kontingent gibt die Anzahl der Anfragenachrichten an, die ein API-Proxy über einen bestimmten Zeitraum verarbeiten kann, z. B. pro Minute, Stunde, Tag, Woche oder Monat. Die Kontingentrichtlinie verwaltet Zähler, die die Anzahl der Anfragen erfassen, die vom API-Proxy empfangen werden. Mit dieser Funktion können API-Anbieter Limits für die Anzahl von API-Aufrufen festlegen, die von Apps über einen bestimmten Zeitraum ausgeführt werden. Mit Kontingentrichtlinien können Sie beispielsweise Anwendungen auf eine Anfrage pro Minute oder 10.000 Anfragen pro Monat beschränken.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Wenn als Kontingent beispielsweise 10.000 Nachrichten pro Monat definiert sind, beginnt die Ratenbegrenzung nach der 10.000. Nachricht. Dabei ist es egal, ob 10.000 Nachrichten am ersten oder letzten Tag dieses Zeitraums gezählt wurden. Es werden keine weiteren Anfragen akzeptiert, bis der Kontingentzähler am Ende des angegebenen Zeitintervalls automatisch zurückgesetzt wird oder bis das Kontingent mithilfe der ResetQuota-Richtlinie explizit zurückgesetzt wird.

Eine Variante der Kontingentrichtlinie namens SpikeArrest-Richtlinie verhindert Trafficspitzen (bzw. Traffic-Bursts), die durch einen plötzlichen Nutzungsanstieg, fehlerhafte Clients oder bösartige Angriffe verursacht werden können.

Mit der Kontingentrichtlinie können Sie die Anzahl der Anfragenachrichten konfigurieren, die ein API-Proxy in einem bestimmten Zeitraum zulässt, z. B. in einer Minute, einer Stunde, einem Tag, einer Woche oder einem Monat. Sie können festlegen, dass das Kontingent für alle Anwendungen, die auf den API-Proxy zugreifen, gleich ist, oder Sie können die Kontingente auf folgenden Grundlagen festlegen:

  • Das Produkt, das den API-Proxy enthält
  • Die Anwendung, die die Anfrage an die API sendet
  • Der Entwickler der Anwendung
  • Viele weitere Kriterien

Verwenden Sie die Kontingentrichtlinie nicht, um Trafficspitzen zu verhindern. Dazu verwenden Sie die SpikeArrest-Richtlinie.

Videos

In diesen Videos wird die Kontingentverwaltung per Kontingentrichtlinie vorgestellt:

Einführung

Dynamisches Kontingent

Verteilt und synchron

Nachrichtengewichtung

Kalender

Rollierendes Zeitfenster

Flexi

Bedingtes Kontingent

Ablaufvariablen

Fehlerbehandlung

Arten von Kontingentrichtlinien

Die Kontingentrichtlinie unterstützt verschiedene Möglichkeiten zum Starten und Zurücksetzen des Kontingentzählers. Sie können festlegen, welche Möglichkeit mit dem Attribut type für das Element <Quota> verwendet werden soll, wie im folgenden Beispiel gezeigt:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

Gültige Werte für type sind:

  • calendar: Konfigurieren Sie ein Kontingent anhand einer expliziten Startzeit. Der Kontingentzähler für jede Anwendung wird anhand der von Ihnen festgelegten Werte für <StartTime>, <Interval> und <TimeUnit> aktualisiert.
  • rollingwindow: Konfigurieren Sie ein Kontingent, das ein „rollierendes Fenster” verwendet, um die Kontingentnutzung zu ermitteln. Mithilfe von rollingwindow legen Sie die Größe des Fensters mit den Elementen <Interval> und <TimeUnit> fest, zum Beispiel 1 Tag. Wenn eine Anfrage eingeht, prüft Apigee die genaue Zeit der Anfrage (z. B. 17:01 Uhr), die Anzahl der Anfragen, die zwischen diesem Zeitpunkt und 17:01 Uhr am Vortag (1 Tag) eingegangen sind, und bestimmt, ob das Kontingent während dieses Zeitfensters überschritten wurde.
  • flexi: Konfigurieren Sie ein Kontingent, das bewirkt, dass der Zähler startet, wenn die erste Anfragenachricht von einer Anwendung empfangen wird, und das auf Grundlage der Werte <Interval> und <TimeUnit> zurückgesetzt wird.

In der folgenden Tabelle werden die Kontingentzurücksetzungen für jeden Typ beschrieben:

Zeiteinheit Typ
default (oder null) calendar flexi
Minute Beginn der nächsten Minute Eine Minute nach <StartTime> Eine Minute nach der ersten Anfrage
Stunde Volle nächste Stunde 1 Stunde nach <StartTime> 1 Stunde nach der ersten Anfrage
Tag Mitternacht GMT des aktuellen Tages 24 Stunden nach <StartTime> 24 Stunden nach der ersten Anfrage
Woche Sonntags um Mitternacht GMT am Ende der Woche Eine Woche nach <StartTime> Eine Woche nach der ersten Anfrage
Monat Mitternacht GMT am letzten Tag des Monats Einen Monat (28 Tage) nach <StartTime> Einen Monat (28 Tage) nach der ersten Anfrage

Für type="calendar" müssen Sie den Wert von <StartTime> angeben.

In der Tabelle ist der Wert für den Typ rollingwindow nicht aufgeführt. Die rollierenden Fensterkontingente werden durch Festlegen der Größe eines Kontingentfensters, z. B. eine Stunde oder ein Zeitfenster, festgelegt. Wenn eine neue Anfrage eingeht, bestimmt die Richtlinie, ob das Kontingent in der Vergangenheit überschritten wurde.

Sie definieren zum Beispiel ein zweistündiges Zeitfenster, in dem 1.000 Anfragen zugelassen werden. Um 16:45 Uhr geht eine neue Anfrage ein. Die Richtlinie berechnet den Kontingentzähler für das letzte Fenster von zwei Stunden, d. h. die Anzahl der Anfragen seit 14:45 Uhr. Wenn das Kontingentlimit in diesem zweistündigen Zeitraum nicht überschritten wurde, wird die Anfrage zugelassen.

Eine Minute später, um 16:46 Uhr, geht eine weitere Anfrage ein. Jetzt berechnet die Richtlinie den Kontingentzähler seit 14:46 Uhr, um zu ermitteln, ob das Limit überschritten wurde.

Beim Typ rollingwindow wird der Zähler nie zurückgesetzt, sondern bei jeder Anfrage neu berechnet.

Informationen zu Kontingentzählern

Bei Ausführung einer Kontingentrichtlinie in einem API-Proxy-Ablauf wird ein Kontingentzähler verringert. Wenn der Zähler sein Limit erreicht, sind keine weiteren API-Aufrufe zulässig, die mit diesem Zähler verknüpft sind. Abhängig von Ihrer Konfiguration kann die Kontingentrichtlinie einen oder mehrere Zähler verwenden. Es ist wichtig zu verstehen, wann mehrere Zähler verwendet werden und wie sie sich verhalten.

So werden Kontingente für API-Produkte gezählt

Wenn Ihr API-Proxy in einem API-Produkt enthalten ist, können Sie die Kontingentrichtlinie so konfigurieren, dass die in diesem Produkt definierten Kontingentregeln verwendet werden. Ein API-Produkt kann Kontingentregeln auf Produktebene oder auf der Ebene einzelner Vorgänge angeben.

Für jeden in einem API-Produkt definierten Vorgang wird ein separater Kontingentzähler verwaltet. Dabei gelten die folgenden Regeln:

  • Wenn für einen Vorgang ein Kontingent definiert ist, haben die Kontingentregeln des Vorgangs Vorrang vor den auf Produktebene definierten Kontingentregeln. Für jeden Vorgang wird ein separater Kontingentzähler erstellt. Durch jeden API-Aufruf an den Pfad eines Vorgangs wird der Zähler erhöht.
  • Wenn für einen Vorgang kein Kontingent definiert ist, wird die Kontingentregel auf Produktebene angewendet. Für den Vorgang wird jedoch ein separater Kontingentzähler verwaltet. In diesem Fall ist es wichtig zu verstehen, dass der Vorgang weiterhin einen eigenen Zähler beibehält, obwohl die Kontingentregel aus der Definition auf Produktebene übernommen wird.
  • Wenn das API-Produkt keine Kontingentdefinitionen enthält – weder auf Produkt- noch auf Vorgangsebene – gelten die in der Richtlinie angegebenen Kontingentregeln. In diesem Fall wird jedoch auch ein separater Kontingentzähler für jeden Vorgang im API-Produkt verwaltet.

In den folgenden Abschnitten werden die Zähleroptionen und das Verhalten genauer beschrieben.

API-Proxy-Zähler konfigurieren

Es ist möglich, ein API-Produkt so zu konfigurieren, dass eine Kontingentanzahl auf dem API-Proxy-Bereich verwaltet wird. In diesem Fall wird die auf API-Produktebene angegebene Kontingentkonfiguration von allen Vorgängen gemeinsam genutzt, für die kein eigenes Kontingent angegeben ist. Durch diese Konfiguration wird ein globaler Zähler auf der API-Proxyebene für dieses API-Produkt erstellt.

Um diese Konfiguration zu erreichen, müssen Sie die /apiproducts Apigee API verwenden, um das Produkt zu erstellen oder zu aktualisieren, und das quotaCountScope-Attribut in der Erstellungs- oder Aktualisierungsanfrage auf PROXY festlegen. In der Konfiguration PROXY nutzen alle Vorgänge, die für das API-Produkt definiert sind, die mit demselben Proxy verknüpft sind und keinen eigenen Zähler haben, denselben Kontingentzähler auf API-Produktebene.

In Abbildung 1 sind die Vorgänge 1 und 2 mit Proxy1 und die Vorgänge 4 und 5 mit Proxy3 verknüpft. Da quotaCounterScope=PROXY im API-Produkt festgelegt ist, teilen sich alle diese Vorgänge die Kontingenteinstellung auf API-Produktebene. Beachten Sie, dass diese Vorgänge zwar die gleiche Kontingentkonfiguration haben, aber je nach Proxy-Verknüpfung separate Zähler verwenden. Für Vorgang 3 gilt jedoch eine eigene Kontingentkonfiguration, sodass es vom Flag quotaCounterScope nicht betroffen ist.

Abbildung 1: Verwendung des Flags „quotaCounterScope“

Wenn für einen Vorgang kein Kontingent definiert ist, wird standardmäßig die Kontingentregel auf Produktebene angewendet. Für den Vorgang wird jedoch ein separater Kontingentzähler verwaltet.

So werden Kontingente gezählt, wenn keine API-Produkte verwendet werden

Wenn mit einem API-Proxy kein API-Produkt verknüpft ist, verwaltet eine Kontingentrichtlinie einen einzelnen Zähler, unabhängig davon, wie oft Sie in einem API-Proxy darauf verweisen. Der Name des Kontingentzählers basiert auf dem Attribut name der Richtlinie.

Sie erstellen beispielsweise eine Kontingentrichtlinie namens MyQuotaPolicy mit einem Limit von fünf Anfragen und platzieren diese in mehreren Abläufen (A, B und C) im API-Proxy. Auch wenn der Zähler in mehreren Abläufen verwendet wird, bleibt er ein einzelner Zähler, der von allen Instanzen der Richtlinie aktualisiert wird:

  • Ablauf A wird ausgeführt -> MyQuotaPolicy wird ausgeführt und der Zähler = 1.
  • Ablauf B wird ausgeführt -> MyQuotaPolicy wird ausgeführt und der Zähler = 2.
  • Ablauf A wird ausgeführt -> MyQuotaPolicy wird ausgeführt und der Zähler = 3.
  • Ablauf C wird ausgeführt -> MyQuotaPolicy wird ausgeführt und der Zähler = 4.
  • Ablauf A wird ausgeführt -> MyQuotaPolicy wird ausgeführt und der Zähler = 5.

Die nächste Anfrage an einen der drei Abläufe wird abgelehnt, da der Kontingentzähler sein Limit erreicht hat.

Die Verwendung derselben Kontingentrichtlinie an mehreren Stellen in einem API-Proxy-Ablauf, die ungewollt dazu führen kann, dass das Kontingent schneller als erwartet verbraucht ist, wird als Anti-Muster bezeichnet (siehe Beschreibung unter Einführung in Antimuster).

Alternativ können Sie mehrere Kontingentrichtlinien in Ihrem API-Proxy definieren und in jedem Ablauf eine andere Richtlinie verwenden. Jede Kontingentrichtlinie nutzt dann einen eigenen Zähler, gemäß dem Attribut name der Richtlinie.

Mehrere Zähler anhand der Richtlinienkonfiguration erstellen

Sie können die Elemente <Class> oder <Identifier> in der Kontingentrichtlinie verwenden, um mehrere eindeutige Zähler in einer einzelnen Richtlinie zu definieren. Wenn Sie diese Elemente verwenden, kann eine einzelne Richtlinie verschiedene Zähler verwalten – auf Grundlage der Anwendung, die die Anfrage stellt, des App-Entwicklers, der die Anfrage stellt, einer Client-ID, einer Client-Kennzeichnung und so weiter. Weitere Informationen zur Verwendung der Elemente <Class> und <Identifier> finden Sie in den obigen Beispielen.

Zeitnotation

Alle Kontingentzeiten sind auf die koordinierte Weltzeit (UTC) eingestellt.

Die Notation der Kontingentzeit entspricht der internationalen Standardnotation, die im internationalen Standard ISO 8601 definiert ist.

Datumsangaben sind als Jahr, Monat und Tag im folgenden Format definiert: YYYY-MM-DD. Beispielsweise steht 2021-02-04 für den 4. Februar 2021.

Die Tageszeit wird im folgenden Format als Stunden, Minuten und Sekunden angegeben: hours:minutes:seconds. Beispielsweise steht 23:59:59 für die Uhrzeit um eine Sekunde vor Mitternacht.

Beachten Sie, dass es zwei Notationen gibt, nämlich 00:00:00 und 24:00:00, um zwischen den beiden Uhrzeiten um Mitternacht zu unterscheiden, die einem Datum zugeordnet werden können. Daher ist 2021-02-04 24:00:00 dasselbe Datum und dieselbe Uhrzeit wie 2021-02-05 00:00:00. Letzteres ist normalerweise die bevorzugte Notation.

Kontingenteinstellungen aus der API-Produktkonfiguration abrufen

Sie können Kontingentlimits in API-Produktkonfigurationen festlegen. Diese Limits erzwingen nicht automatisch ein Kontingent. Stattdessen können Sie in einer Kontingentrichtlinie auf die Einstellungen für das Produktkontingent verweisen. Beim Festlegen eines Kontingents für das Produkt haben Sie folgende Vorteile:

  • Bei Kontingentrichtlinien kann eine einheitliche Einstellung für alle API-Proxys im API-Produkt verwendet werden.
  • Sie können Laufzeitänderungen an der Kontingenteinstellung eines API-Produkts vornehmen. Außerdem haben Kontingentrichtlinien, die auf den Wert verweisen, automatisch aktualisierte Kontingentwerte.

Weitere Informationen zur Verwendung der Kontingenteinstellungen aus einem API-Produkt finden Sie im obigen Beispiel „Dynamisches Kontingent”.

Informationen zum Konfigurieren von API-Produkten mit Kontingentlimits finden Sie unter API-Produkte verwalten.

Zähler für gemeinsame Kontingente konfigurieren

In der Regel zählt die Kontingentrichtlinie alle Anfragen, die an einen API-Proxy gesendet werden. In einigen Anwendungsfällen möchten Sie möglicherweise das Kontingent für eingehende Anfragen erzwingen, aber auch die Kontingente für Zielantworten, die eine bestimmte Bedingung erfüllen, erhöhen. Wenn Sie drei Kontingentrichtlinienelemente zusammen verwenden, <SharedName>, <CountOnly> und <EnforceOnly>, können Sie die Kontingentrichtlinie anpassen, um das eingehende Anfragekontingent zu erzwingen und Zielantworten basierend auf einem Bedingungen, die Sie angeben.

Angenommen, Sie möchten den Kontingentzähler für einen API-Proxy erhöhen, bei dem die Antworten vom Back-End-Ziel den HTTP-Statuscode 200 haben. Gehen Sie so vor, um diese spezialisierte Zählung zu erreichen:

  • Fügen Sie dem ProxyEndpoint-Anfrageablauf eine Kontingentrichtlinie hinzu, bei der das Element <SharedName> mit einem Namenswert und das Element <EnforceOnly> auf true festgelegt ist.
  • Fügen Sie dem ProxyEndpoint-Antwortablauf eine weitere Kontingentrichtlinie hinzu. Dabei muss das Element <SharedName> denselben Namenswert wie die erste Richtlinie haben und das Element <CountOnly> auf true.
  • Platzieren Sie die zweite Kontingentrichtlinie (die mit <CountOnly>) in einem bedingten Schritt, der die Bedingung festlegt, für die der Kontingentzähler erhöht werden soll.

Ein Beispiel für die Verwendung freigegebener Zähler finden Sie unter Freigegebene Zähler im Abschnitt Beispiele.

Beispiele

Diese Codebeispiele für Richtlinien zeigen, wie Sie das Start- und Enddatum für Kontingente festlegen:

Dynamischere Kontingente

<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>

Mit dynamischen Kontingenten können Sie eine einzelne Kontingentrichtlinie konfigurieren, die verschiedene Kontingenteinstellungen anhand der Angaben erzwingt, die an die Kontingentrichtlinie übergeben werden. Eine weitere Bezeichnung für die Kontingenteinstellungen in diesem Kontext ist der Serviceplan. Das dynamische Kontingent prüft den Serviceplan der Anwendungen und erzwingt diese Einstellungen.

Wenn Sie beispielsweise ein API-Produkt erstellen, können Sie optional das zulässige Kontingentlimit, die Zeiteinheit und das Intervall festlegen. Wenn Sie diesen Wert für das API-Produkt festlegen, wird die Verwendung in einem API-Proxy jedoch nicht erzwungen. Sie müssen außerdem eine Kontingentrichtlinie zum API-Proxy hinzufügen, die diese Werte liest. Weitere Informationen finden Sie unter API-Produkte erstellen.

Im obigen Beispiel verwendet der API-Proxy, der die Kontingentrichtlinie enthält, eine Richtlinie VerifyAPIKey mit dem Namen verify-api-key, um den in einer Anfrage übergebenen API-Schlüssel zu validieren. Die Kontingentrichtlinie greift dann auf die Ablaufvariablen aus der VerifyAPIKey-Richtlinie zu, um die für das API-Produkt festgelegten Kontingentwerte zu lesen.

Eine weitere Option besteht darin, benutzerdefinierte Attribute für einzelne Entwickler oder Anwendungen festzulegen und diese Werte dann in der Kontingentrichtlinie zu lesen. Beispiel: Um verschiedene Kontingentwerte pro Entwickler festzulegen, legen Sie benutzerdefinierte Attribute für den Entwickler fest, die das Limit, die Zeiteinheit und das Intervall enthalten. Verweisen Sie dann in der Kontingentrichtlinie auf diese Werte:

<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>

In diesem Beispiel werden auch die VerifyAPIKey-Ablaufvariablen verwendet, um auf die benutzerdefinierten Attribute zu verweisen, die für den Entwickler festgelegt wurden.

Sie können eine beliebige Variable verwenden, um die Parameter der Kontingentrichtlinie festzulegen. Diese Variablen können aus folgenden Quellen stammen:

  • Ablaufvariablen
  • Attribute für das API-Produkt, die Anwendung oder den Entwickler
  • Eine Schlüssel/Wert-Paar-Zuordnung (KVM)
  • Header, Abfrageparameter, Formularparameter und anderes

Sie können für jeden API-Proxy eine Kontingentrichtlinie hinzufügen, die entweder auf dieselbe Variable verweist wie alle anderen Kontingentrichtlinien in allen anderen Proxys oder die Kontingentrichtlinie kann auf Variablen verweisen, die für diese Richtlinie und diesen Proxy einzigartig sind.

Beginn

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

Für ein Kontingent, bei dem type als calendar festgelegt ist, müssen Sie einen expliziten Wert <StartTime> festlegen. Der Zeitwert ist die GMT-Zeit, nicht die Ortszeit. Wenn Sie keinen <StartTime>-Wert für eine Richtlinie vom Typ calendar angeben, gibt Apigee einen Fehler aus.

Der Kontingentzähler wird pro Anwendung anhand der Werte <StartTime>, <Interval> und <TimeUnit> aktualisiert. In diesem Beispiel beginnt das Kontingent am 18. Februar 2021 um 10:30 Uhr GMT zu zählen. Die Aktualisierung erfolgt alle 5 Stunden. Die nächste Aktualisierung erfolgt also am 18. Februar 2021 um 15:30 Uhr GMT.

Access Counter

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

Ein API-Proxy hat Zugriff auf die durch die Kontingentrichtlinie festgelegten Flussvariablen. Sie können auf diese Flussvariablen im API-Proxy zugreifen, um eine bedingte Verarbeitung durchzuführen, die Richtlinie im Blick zu behalten, wenn das Kontingentlimit erreicht wird, den aktuellen Kontingentzähler an eine Anwendung zurückzugeben oder aus anderen Gründen.

Da der Zugriff auf die Flussvariablen für die Richtlinie auf dem Attribut name der Richtlinie basiert, greifen Sie für die oben genannte Richtlinie mit dem Namen <Quota> so auf die Flussvariablen zu:

  • ratelimit.QuotaPolicy.allowed.count: Zugelassene Menge.
  • ratelimit.QuotaPolicy.used.count: Aktueller Zählerwert.
  • ratelimit.QuotaPolicy.expiry.time: UTC-Zeit, zu der der Zähler zurückgesetzt wird.

Es gibt viele weitere Flussvariablen, auf die Sie wie unten beschrieben zugreifen können.

Sie können beispielsweise die folgende AssignMessage-Richtlinie verwenden, um die Werte der Flussvariablen eines Kontingents als Antwortheader zurückzugeben:

<AssignMessage 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>

Freigegebene Zähler

Das folgende Beispiel zeigt, wie ein gemeinsam genutzter Zähler für einen API-Proxy konfiguriert wird, wobei der Kontingentzähler auch erhöht wird, wenn die Zielantwort der HTTP-Status 200 ist. Da beide Kontingentrichtlinien denselben <SharedName>-Wert verwenden, teilen sich beide Kontingentrichtlinien denselben Kontingentzähler. Weitere Informationen finden Sie unter Freigegebene Kontingentzähler konfigurieren.

Beispiel für eine ProxyEndpoint-Konfiguration: 

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

Beispiel für die erste Kontingentrichtlinie:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

Beispiel für eine zweite Kontingentrichtlinie:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

First Request

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

Verwenden Sie diesen Beispielcode, um ein Kontingent von 10.000 Aufrufen pro Stunde zu erzwingen. Die Richtlinie setzt den Kontingentzähler zu jeder vollen Stunde zurück. Wenn der Zähler das Kontingent von 10.000 Aufrufen vor Ablauf der Stunde erreicht, werden weitere Aufrufe abgelehnt.

Wenn der Zähler beispielsweise bei 2021-07-08 07:00:00 beginnt, wird der Wert am 2021-07-08 08:00:00 (eine Stunde ab der Startzeit) auf 0 zurückgesetzt. Wenn die erste Nachricht am 2021-07-08 07:35:28 eingeht und die Anzahl der Nachrichten vor 2021-07-08 08:00:00 10.000 erreicht hat, werden weitere Aufrufe abgelehnt, bis der Zähler zur vollen Stunde zurückgesetzt wird.

Die Zeit bis zum Zurücksetzen des Zählers basiert auf der Kombination aus <Interval> und <TimeUnit>. Wenn Sie beispielsweise <Interval> für eine <TimeUnit>-Stunde auf 12 setzen, wird der Zähler alle 12 Stunden zurückgesetzt. Sie können <TimeUnit> auf Minute, Stunde, Tag, Woche oder Monat festlegen.

Sie können in Ihrem API-Proxy an mehreren Stellen auf diese Richtlinie verweisen. Sie können es beispielsweise im Proxy-PreFlow platzieren, damit er bei jeder Anfrage ausgeführt wird. Alternativ können Sie sie auch in mehreren Abläufen im API-Proxy platzieren. Wenn Sie diese Richtlinie an mehreren Stellen im Proxy verwenden, wird ein einzelner Zähler verwaltet, der von allen Instanzen der Richtlinie aktualisiert wird.

Alternativ können Sie mehrere Kontingentrichtlinien in Ihrem API-Proxy definieren. Jede Kontingentrichtlinie nutzt dann einen eigenen Zähler, gemäß dem Attribut name der Richtlinie.

ID festlegen

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

Bei einer Kontingentrichtlinie wird standardmäßig ein einzelner Zähler für den API-Proxy definiert, unabhängig vom Ursprung einer Anfrage. Alternativ können Sie bei einer Kontingentrichtlinie das Attribut <Identifier> verwenden, um separate Zähler basierend auf dem Wert des Attributs <Identifier> zu verwalten.

Beispielsweise können Sie mit dem Tag <Identifier> separate Zähler für jede Client-ID definieren. Bei einer Anfrage an Ihren Proxy übergibt die Clientanwendung, wie im obigen Beispiel gezeigt, einen Header, der clientID enthält.

Sie können eine beliebige Ablaufvariable im Attribut <Identifier> angeben. Beispiel: Sie können angeben, dass ein Abfrageparameter namens id die eindeutige Kennzeichnung enthält:

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

Wenn Sie die VerifyAPIKey-Richtlinie zur Validierung des API-Schlüssels oder der OAuthV2-Richtlinien mit OAuth-Tokens verwenden, können Sie Informationen im API-Schlüssel oder -Token nutzen, um einzelne Zähler für dieselbe Kontingentrichtlinie zu definieren. Beispiel: Folgendes <Identifier>-Element verwendet die Ablaufvariable client_id einer VerifyAPIKey-Richtlinie mit dem Namen verify-api-key:

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

Jeder eindeutige client_id-Wert definiert nun einen eigenen Zähler in der Kontingentrichtlinie.

Klasse

<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>

Sie können Kontingentlimits dynamisch festlegen, indem Sie eine klassenbasierte Kontingentzählung verwenden. In diesem Beispiel wird das Kontingentlimit durch den Wert des Headers developer_segment bestimmt, der mit jeder Anfrage übergeben wird. Diese Variable kann den Wert platinum oder silver haben. Wenn der Header einen ungültigen Wert enthält, gibt die Richtlinie einen Fehler wegen Kontingentverletzung zurück.

Element <Quota>

Im Folgenden sind Attribute und untergeordnete Elemente von <Quota> aufgeführt. Beachten Sie, dass einige Elementkombinationen sich gegenseitig ausschließen oder nicht erforderlich sind. Unter den jeweiligen Beispielen werden konkrete Anwendungsfälle gezeigt.

Die unten aufgeführten verifyapikey.my-verify-key-policy.apiproduct.*-Variablen sind standardmäßig verfügbar, wenn eine VerifyAPIKey-Richtlinie namens my-verify-key-policy verwendet wird, um den API-Schlüssel der Anwendung in der Anfrage zu prüfen. Die Variablenwerte stammen aus den Kontingenteinstellungen des API-Produkts, dem der Schlüssel zugeordnet ist, wie unter Kontingenteinstellungen aus der API-Produktkonfiguration abrufen beschrieben.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

Die folgenden Attribute sind spezifisch für diese Richtlinie:

Attribut Beschreibung Standard Presence
Typ

Legt den Typ der Kontingentrichtlinie fest, der bestimmt, wann und wie der Kontingentzähler die Kontingentnutzung geprüft und wie er zurückgesetzt wird.

Wenn Sie type nicht festlegen, beginnt der Zähler am Anfang der Minute, der Stunde, des Tags, der Woche oder des Monats.

Gültige Werte sind:

  • calendar
  • rollingwindow
  • flexi

Eine vollständige Beschreibung der einzelnen Typen finden Sie unter Kontingentrichtlinientypen.

 – Optional

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut Beschreibung Standard Presence
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch:

 false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Verworfen

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>
Standard

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence Optional
Typ String

<Allow>

Gibt das numerische Limit für das Kontingent an. Wenn der Zähler für die Richtlinie dieses Limit erreicht, werden nachfolgende Aufrufe abgelehnt, bis der Zähler zurückgesetzt wird.

Kann auch ein <Class>-Element enthalten, das das <Allow>-Element basierend auf einer Ablaufvariable konditioniert.

Standardwert –
Erforderlich? Optional
Typ Ganzzahl- oder komplexer Typ
Übergeordnetes Element <Quota>
Untergeordnete Elemente <Class>

Hier sehen Sie drei Möglichkeiten zum Festlegen des Elements <Allow>:

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

Wenn Sie sowohl count als auch countRef angeben, erhält countRef die Priorität. Wenn countRef zur Laufzeit nicht aufgelöst wird, wird der Wert von count verwendet.

Sie können auch ein <Class>-Element als untergeordnetes Element von <Allow> angeben, um die zulässige Anzahl der Richtlinie auf Basis einer Ablaufvariable zu bestimmen. Apigee ordnet den Wert der Ablaufvariable wie unten dargestellt dem Attribut class des <Allow>-Elements zu:

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

In der folgenden Tabelle sind die Attribute von <Allow> aufgeführt:

Attribut Beschreibung Standard Presence
count

Dient zum Angeben einer Nachrichtenzahl für das Kontingent.

Ein Wert von 100 für das Attribut count, ein Interval von 1 und die TimeUnit "Monat" geben beispielsweise ein Kontingent von 100 Nachrichten pro Monat an.

 2000 Optional
countRef

Dient zum Angeben einer Ablaufvariable, die die Nachrichtenanzahl für ein Kontingent enthält. countRef hat Vorrang vor dem Attribut count.

 keine Optional

<Class>

Damit können Sie den Wert des Elements <Allow> basierend auf dem Wert einer Ablaufvariablen konditionieren. Für jedes unterschiedliche untergeordnete <Allow>-Tag von <Class> verwaltet die Richtlinie einen anderen Zähler.

Standardwert –
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Allow>
Untergeordnete Elemente <Allow> (untergeordnet unter <Class>)

Wenn Sie das <Class>-Element verwenden möchten, geben Sie eine Ablaufvariable mithilfe des Attributs ref für das Element <Class> an. Apigee wählt dann anhand des Werts der Ablaufvariablen eines der untergeordneten <Allow>-Elemente aus, um die zulässige Anzahl der Richtlinie zu bestimmen. Apigee ordnet den Wert der Ablaufvariable wie unten dargestellt dem Attribut class des <Allow>-Elements zu:

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

In diesem Beispiel wird der aktuelle Kontingentzähler durch den Wert des an Ihrer Anfrage übergebenen Abfrageparameters time_variable bestimmt. Diese Variable kann den Wert peak_time oder off_peak_time haben. Wenn der Abfrageparameter einen ungültigen Wert enthält, gibt die Richtlinie einen Fehler wegen Kontingentverletzung zurück.

In der folgenden Tabelle sind die Attribute von <Class> aufgeführt:

Attribut Beschreibung Standard Presence
ref Dient zum Angeben einer Ablaufvariable, die die Kontingentklasse für ein Kontingent enthält. keine Erforderlich

<Allow> (untergeordnet unter <Class>)

Gibt das Limit für einen Kontingentzähler an, der durch das Element <Class> definiert wird. Für jedes unterschiedliche untergeordnete <Allow>-Tag von <Class> verwaltet die Richtlinie einen anderen Zähler.

Standardwert –
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Class>
Untergeordnete Elemente Keins

Beispiele:

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

In diesem Beispiel nutzt die Kontingentrichtlinie zwei Kontingentzähler mit den Namen peak_time und off_peak_time. Welcher konkret verwendet wird, hängt vom Abfrageparameter ab, der übergeben wird (siehe <Class>-Beispiel).

In der folgenden Tabelle sind die Attribute von <Allow> aufgeführt:

Attribut Beschreibung Standard Presence
Klasse Definiert den Namen des Kontingentzählers. keine Erforderlich
count Gibt das Kontingentlimit für den Zähler an. keine Erforderlich

<Interval>

Gibt die Anzahl der Zeiträume an, in denen Kontingente berechnet werden.

Standardwert –
Erforderlich? Erforderlich
Typ Ganzzahl
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Wird zur Angabe einer Ganzzahl verwendet (z. B. 1, 2, 5, 60 usw.), die mit dem von Ihnen angegebenen <TimeUnit>-Element (Minute, Stunde, Tag, Woche oder Monat) gekoppelt wird, um einen Zeitraum zu bestimmen, in dem Apigee die Kontingentnutzung berechnet.

Zum Beispiel ein Intervall von 24 mit einer <TimeUnit> von hour bedeutet, dass das Kontingent über einen Zeitraum von 24 Stunden berechnet wird.

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

In der folgenden Tabelle sind die Attribute von <Interval> aufgeführt:

Attribut Beschreibung Standard Presence
ref

Wird verwendet, um eine Ablaufvariable anzugeben, die das Intervall für ein Kontingent enthält. ref hat Vorrang vor einem expliziten Intervallwert. Wenn sowohl Referenz als auch Wert angegeben sind, erhält die Referenz die Priorität. Wenn ref nicht zur Laufzeit aufgelöst wird, wird der Wert verwendet.

 keine Optional

<TimeUnit>

Gibt die für das Kontingent geltende Zeiteinheit an.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Wählen Sie minute, hour, day, week, month oder year aus.

Ein Interval von 24 mit einer TimeUnit von hour bedeutet, dass das Kontingent über einen Zeitraum von 24 Stunden berechnet wird.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Standard: keine
Präsenz: Erforderlich
Typ: String

In der folgenden Tabelle sind die Attribute von <TimeUnit> aufgeführt:

Attribut Beschreibung Standard Presence
ref Gibt eine Ablaufvariable an, die die Zeiteinheit für ein Kontingent enthält. ref hat Vorrang vor einem expliziten Intervallwert. Wenn ref nicht zur Laufzeit aufgelöst wird, wird der Intervallwert verwendet. keine Optional

<StartTime>

Wenn type auf calendar gesetzt ist, werden hiermit Datum und Uhrzeit für den Start des Kontingentzählers angegeben, unabhängig davon, ob Anfragen von Anwendungen empfangen wurden.

Standardwert –
Erforderlich? Optional (erforderlich, wenn type auf calendar gesetzt ist)
Typ String im Datums- und Zeitformat nach ISO 8601.
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Sie müssen eine explizite <StartTime> angeben, wenn type auf calendar festgelegt ist; Sie können keine Referenz auf eine Ablaufvariable verwenden. Falls Sie einen <StartTime>-Wert angeben, wenn kein type-Wert festgelegt ist, gibt Apigee einen Fehler zurück.

Beispiele:

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

<Distributed>

Bestimmt, ob Apigee einen oder mehrere Knoten zum Verarbeiten von Anfragen verwendet.

Standardwert false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Setzen Sie den Wert auf true, um anzugeben, dass die Richtlinie einen zentralen Zähler beibehalten und fortlaufend auf allen Knoten synchronisieren soll. Die Knoten können sich in Verfügbarkeitszonen und/oder Regionen befinden.

Wenn Sie den Standardwert false verwenden, kann Ihr Kontingent überschritten werden, da der Zähler für jeden Knoten nicht geteilt wird:

<Distributed>false</Distributed>

Um dafür zu sorgen, dass die Zähler bei jeder Anfrage synchronisiert und aktualisiert werden, legen Sie <Distributed> und <Synchronous> auf true fest:

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

<Synchronous>

Legt fest, ob ein verteilter Kontingentzähler synchron aktualisiert wird.

Standardwert false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Legen Sie true fest, um einen verteilten Kontingentzähler synchron zu aktualisieren. Dies bedeutet, dass die Aktualisierungen an den Zählern gleichzeitig durchgeführt werden, wenn das Kontingent für eine Anfrage an die API geprüft wird. Setzen Sie den Wert auf true, wenn Sie keine API-Aufrufe über das Kontingent zulassen möchten.

Setzen Sie den Wert auf false, um den Kontingentzähler asynchron zu aktualisieren. Dies bedeutet, dass einige API-Aufrufe trotz Überschreitung des Kontingents möglicherweise ausgeführt werden. Dies hängt davon ab, wann der Kontingentzähler im zentralen Repository asynchron aktualisiert wird. Es bestehen jedoch keine Auswirkungen auf die Leistung wie bei einer synchronen Aktualisierung.

Bei asynchroner Aktualisierung beträgt das Standardaktualisierungsintervall 10 Sekunden. Verwenden Sie das Element <AsynchronousConfiguration>, um dieses asynchrone Verhalten zu konfigurieren.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Konfiguriert das Synchronisierungsintervall zwischen verteilten Kontingentzählern, wenn das Richtlinienkonfigurationselement <Synchronous> nicht vorhanden ist oder vorhanden und auf false festgelegt ist. Apigee ignoriert dieses Element, wenn <Synchronous> auf true festgelegt ist.

Standardwert –
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Quota>
Untergeordnete Elemente <SyncIntervalInSeconds>
<SyncMessageCount>

Sie können das Synchronisierungsverhalten mit den untergeordneten Elementen <SyncIntervalInSeconds> oder <SyncMessageCount> festlegen. Verwenden Sie ein oder beide Elemente. Beispiel:

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

oder

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Wenn nur <SyncIntervalInSeconds> vorhanden ist, wird das Kontingent alle N Sekunden synchronisiert, wobei N der im Element angegebene Wert ist, unabhängig davon, wie viele Nachrichten verarbeitet wurden.
  • Wenn nur <SyncMessageCount> vorhanden ist, wird das Kontingent alle M Nachrichten synchronisiert, wobei M der im Element angegebene Wert ist, oder alle 10 Sekunden, je nachdem, was zuerst eintritt.
  • Wenn beide Elemente vorhanden sind, wird das Kontingent alle M Nachrichten oder alle N Sekunden synchronisiert, je nachdem, was zuerst eintritt.
  • Wenn <AsynchronousConfiguration> oder kein untergeordnetes Element vorhanden ist, wird das Kontingent alle 10 Sekunden synchronisiert, unabhängig davon, wie viele Nachrichten verarbeitet wurden.

<SyncIntervalInSeconds>

Überschreibt das Standardverhalten, in dem asynchrone Updates nach einem Intervall von 10 Sekunden ausgeführt werden.

Standardwert 10 Sekunden
Erforderlich? Optional
Typ Ganzzahl
Übergeordnetes Element <AsynchronousConfiguration>
Untergeordnete Elemente Keins
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

Das Synchronisierungsintervall muss mindestens 10 Sekunden lang sein, wie unter Limits beschrieben.

<SyncMessageCount>

Gibt die Anzahl der Anfragen an, die vor der Synchronisierung des Kontingentzählers verarbeitet werden sollen.

Standardwert –
Erforderlich? Optional
Typ Ganzzahl
Übergeordnetes Element <AsynchronousConfiguration>
Untergeordnete Elemente Keins
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Mit der Konfiguration in diesem Beispiel wird auf jedem Knoten die Kontingentanzahl nach allen 5 Anfragen oder alle 10 Sekunden synchronisiert, je nachdem, was zuerst eintritt.

<Identifier>

Konfiguriert die Richtlinie, um eindeutige Zähler anhand einer Ablaufvariablen zu erstellen.

Standardwert –
Erforderlich? Optional
Typ String
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Mit dem Kennzeichnungselement können Sie bestimmten Buckets Aufrufe zuweisen, die durch den Wert in einer Ablaufvariable definiert werden. Sie können beispielsweise die Variable developer.id verwenden, die nach einer VerifyAPIKey-Richtlinie ausgefüllt wird, um ein Kontingentlimit für alle Instanzen aller von den jeweils angegebenen Entwicklern erstellten Anwendungen zu erzwingen. Alternativ können Sie client_id verwenden, um ein Kontingentlimit für jede bestimmte Anwendung zu erzwingen. Die Konfiguration für die zweite Option sieht so aus:

<Identifier ref="client_id"/>

Sie können entweder auf eine benutzerdefinierte Variable verweisen, die Sie mit der AssignMessage-Richtlinie oder der JavaScript-Richtlinie erstellen können, oder auf eine implizit festgelegte Variable wie sie von der VerifyAPIKey-Richtlinie oder der VerifyJWT-Richtlinie eingestellt wird. Weitere Informationen zu Variablen finden Sie unter Ablaufvariablen verwenden. Eine Liste der von Apigee definierten bekannten Variablen finden Sie in der Übersicht über Ablaufvariablen.

Wenn Sie dieses Element nicht verwenden, weist die Richtlinie alle Aufrufe in einem einzelnen Zähler für die jeweilige Kontingentrichtlinie zu.

Dieses Element wird auch unter Wie funktioniert die Kontingentrichtlinie, wenn keine Kennung angegeben wird? diskutiert.

In der folgenden Tabelle werden die Attribute von <Identifier> beschrieben:

Attribut Beschreibung Standard Presence
ref

Gibt eine Flussvariable an, mit der der Zähler identifiziert wird, der für die Anfrage verwendet wird. Die Variable kann auf einen HTTP-Header, einen Abfrageparameter, einen Formularparameter oder ein Element des Nachrichteninhalts oder einen anderen Wert verweisen, mit dem angegeben wird, wie die Aufrufmengen zugewiesen werden.

client_id wird im Allgemeinen als Variable verwendet. Der client_id wird auch als API-Schlüssel oder Consumer-Schlüssel bezeichnet und für eine Anwendung generiert, wenn sie in einer Organisation in Apigee registriert wird. Sie können diese ID verwenden, wenn Sie für Ihre API die API-Schlüssel- oder OAuth-Autorisierungsrichtlinien aktiviert haben.

 – Optional

<MessageWeight>

Gibt die Kosten an, die jeder Nachricht für Kontingentzwecke zugewiesen sind. Verwenden Sie dieses Element, um die Wirkung von Anfragenachrichten zu erhöhen, die beispielsweise mehr Rechenleistung verbrauchen als andere.

Standardwert –
Erforderlich? Optional
Typ Ganzzahl
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Beispiel: Sie möchten POST-Nachrichten als doppelt so teuer zählen wie GET-Nachrichten. Setzen Sie daher <MessageWeight> auf 2 für einen POST und auf 1 für GET. Sie können sogar den Wert <MessageWeight> auf 0 festlegen, sodass sich die Anfrage nicht auf den Zähler auswirkt.

Wenn das Kontingent in diesem Beispiel 10 Nachrichten pro Minute beträgt und die Anfrage <MessageWeight> für POST den Wert 2 hat, erlaubt das Kontingent fünf POST-Anfragen in jedem 10 Minuten-Intervall. Zusätzliche Anfragen, POST oder GET, bevor das Zurücksetzen des Zählers abgelehnt wird.

Ein Wert, der <MessageWeight> darstellt, muss durch eine Flussvariable angegeben werden und kann aus HTTP-Headern, Abfrageparametern, einer XML- oder JSON-Anfragenutzlast oder einer anderen Flussvariablen extrahiert werden. Legen Sie sie beispielsweise in einem Header mit dem Namen weight fest:

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

Definiert Kontingenteinstellungen für ein API-Produkt, z. B. Zeiteinheiten, Intervalle und Maximalwerte.

Standardwert –
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Quota>
Untergeordnete Elemente <DefaultConfig>

Wenn Sie der Kontingentrichtlinie das Element <UseQuotaConfigInAPIProduct> hinzufügen, ignoriert Apigee alle untergeordneten Elemente <Allow>, <Interval> und <TimeUnit> von <Quota>.

Das <UseQuotaConfigInAPIProduct>-Element ist einfach ein Container für die Standardeinstellungen, die Sie mithilfe des Elements <DefaultConfig> definieren, wie das folgende Beispiel zeigt:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Sie können mit dem Attribut stepName entweder auf eine VerifyAPIKey-Richtlinie oder auf einen ValidateToken-Richtlinienvorgang der OAuthv2-Richtlinie im Ablauf verweisen.

In der folgenden Tabelle werden die Attribute von <UseQuotaConfigInAPIProduct> beschrieben:

Attribut Beschreibung Standard Presence
stepName Gibt den Namen der Authentifizierungsrichtlinie im Ablauf an. Das Ziel kann entweder eine VerifyAPIKey-Richtlinie oder eine OAuthv2-Richtlinie sein. – Erforderlich

Hier finden Sie weitere Informationen:

<DefaultConfig>

Enthält Standardwerte für das Kontingent eines API-Produkts. Wenn Sie eine <DefaultConfig> definieren, sind alle drei untergeordneten Elemente erforderlich.

Standardwert –
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <UseQuotaConfigInAPIProduct>
Untergeordnete Elemente <Allow>
<Interval>
<TimeUnit>

Es ist möglich, diese Werte sowohl für den Vorgang des API-Produkts (entweder über die Benutzeroberfläche oder über die API für API-Produkte) als auch in der Kontingentrichtlinie zu definieren. In diesem Fall haben die Einstellungen im API-Produkt jedoch Vorrang und die Einstellungen in der Kontingentrichtlinie werden ignoriert.

Die Syntax für dieses Element sieht so aus:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

Im folgenden Beispiel wird ein Kontingent von 10.000 pro Woche angegeben:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Hier finden Sie weitere Informationen:

<SharedName>

Gibt diese Kontingentrichtlinie als shared an. Alle Kontingentrichtlinien in einem API-Proxy mit demselben <SharedName>-Wert haben denselben zugrunde liegenden Kontingentzähler. Wenn dieses Element vorhanden ist, müssen auch die Elemente <EnforceOnly> oder <CountOnly> vorhanden sein.

Weitere Informationen und Beispiele finden Sie unter Freigegebene Kontingentzähler konfigurieren.

Standardwert –
Erforderlich? Optional
Typ String
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

<CountOnly>

Platzieren Sie eine Kontingentrichtlinie, bei der dieses Element auf true gesetzt ist, in einem bedingten Schritt im ProxyEndpoint-Antwortablauf, um den zugrunde liegenden Kontingentzähler bedingt zu erhöhen. Wenn dieses Element vorhanden ist, müssen auch die Elemente <SharedName> und <EnforceOnly> vorhanden sein.

Weitere Informationen und Beispiele finden Sie unter Freigegebene Kontingentzähler konfigurieren.

Standardwert false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

<EnforceOnly>

Legen Sie im Anfrageablauf eines API-Proxys eine Kontingentrichtlinie fest, für die dieses Element auf true festgelegt ist. Mit dieser Konfiguration können Kontingentzahlen für jede Kontingentrichtlinie im API-Proxy mit demselben <SharedName>-Wert freigegeben werden. Wenn dieses Element vorhanden ist, müssen auch die Elemente <SharedName> und <CountOnly> vorhanden sein.

Weitere Informationen und Beispiele finden Sie unter Freigegebene Kontingentzähler konfigurieren.

Standardwert false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <Quota>
Untergeordnete Elemente Keins

Ablaufvariablen

Die folgenden vordefinierten Flussvariablen beim Ausführen einer Kontingentrichtlinie automatisch ausgefüllt. Weitere Informationen finden Sie unter Referenz zu Ablaufvariablen.

Variablen Typ Berechtigungen Beschreibung
ratelimit.{policy_name}.allowed.count Long Schreibgeschützt: Gibt die zulässige Kontingentzahl zurück.
ratelimit.{policy_name}.used.count Long Schreibgeschützt: Gibt das aktuell in einem Kontingentintervall verwendete Kontingent zurück.
ratelimit.{policy_name}.available.count Long Schreibgeschützt: Gibt die verfügbare Kontingentzahl im Kontingentintervall zurück.
ratelimit.{policy_name}.exceed.count Long Schreibgeschützt: Gibt 1 zurück, wenn das Kontingent überschritten wurde.
ratelimit.{policy_name}.total.exceed.count Long Schreibgeschützt: Gibt 1 zurück, wenn das Kontingent überschritten wurde.
ratelimit.{policy_name}.expiry.time Long Schreibgeschützt:

Gibt die UTC-Zeit in Millisekunden zurück. Damit wird festgelegt, wann das Kontingent abläuft und ein neues Kontingentintervall beginnt.

Wenn der Typ der Kontingentrichtlinie rollingwindow lautet, ist dieser Wert nicht gültig, da das Kontingentintervall niemals abläuft.
ratelimit.{policy_name}.identifier String Schreibgeschützt: Gibt den mit der Richtlinie verknüpften (Client-)ID-Verweis zurück
ratelimit.{policy_name}.class String Schreibgeschützt: Gibt die der Client-ID zugeordnete Klasse zurück
ratelimit.{policy_name}.class.allowed.count Long Schreibgeschützt: Gibt die in der Klasse definierte zulässige Kontingentzahl zurück
ratelimit.{policy_name}.class.used.count Long Schreibgeschützt: Gibt das verwendete Kontingent innerhalb einer Klasse zurück.
ratelimit.{policy_name}.class.available.count Long Schreibgeschützt: Gibt die verfügbare Kontingentzahl in der Klasse zurück
ratelimit.{policy_name}.class.exceed.count Long Schreibgeschützt: Gibt die Anzahl der Anfragen zurück, die das Limit in der Klasse im aktuellen Kontingentintervall überschreiten.
ratelimit.{policy_name}.class.total.exceed.count Long Schreibgeschützt: Gibt die Gesamtzahl der Anfragen zurück, die das Limit in der Klasse aller Kontingentintervalle überschreiten. Es ist also die Summe von class.exceed.count für alle Kontingentintervalle.
ratelimit.{policy_name}.failed Boolesch Schreibgeschützt:

Gibt an, ob die Richtlinie fehlgeschlagen ist ("true" oder "false").

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Diverse Fehlerkorrekturen
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Tritt auf, wenn das <Interval>-Element nicht in der Quota-Richtlinie definiert ist. Dieses Element ist obligatorisch und wird verwendet, um das Zeitintervall anzugeben, das für das Kontingent gilt. Das Zeitintervall kann Minuten, Stunden, Tage, Wochen oder Monate sein, wie mit dem <TimeUnit>-Element definiert.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Tritt auf, wenn das <TimeUnit>-Element nicht in der Quota-Richtlinie definiert ist. Dieses Element ist obligatorisch und wird verwendet, um die Zeiteinheit anzugeben, die für das Kontingent gilt. Das Zeitintervall kann in Minuten, Stunden, Tagen, Wochen oder Monaten angegeben werden.
policies.ratelimit.InvalidMessageWeight 500 Tritt auf, wenn der Wert des <MessageWeight>-Elements, das über eine Ablaufvariable angegeben wird, ungültig ist (ein ganzzahliger Wert).
policies.ratelimit.QuotaViolation 500 Das Kontingentlimit wurde überschritten. –

Bereitstellungsfehler

Fehlername Ursache Diverse Fehlerkorrekturen
InvalidQuotaInterval Wenn das im <Interval>-Element angegebene Kontingentintervall keine Ganzzahl ist, schlägt die Bereitstellung des API-Proxys fehl. Wenn das angegebene Kontingentintervall beispielsweise 0,1 im <Interval>-Element lautet, schlägt die Bereitstellung des API-Proxys fehl.
InvalidQuotaTimeUnit Wenn die im <TimeUnit>-Element angegebene Zeiteinheit nicht unterstützt wird, schlägt die Bereitstellung des API-Proxys fehl. Die unterstützten Zeiteinheiten sind minute, hour, day, week und month.
InvalidQuotaType Wenn der Typ des Kontingents, das im <Quota>-Attribut des type-Attribut angegeben ist, ungültig ist, dann schlägt die Bereitstellung des API-Proxys fehl. Unterstützte Kontingenttypen sind default, calendar, flexi und rollingwindow.
InvalidStartTime Wenn das im <StartTime>-Element angegebene Zeitformat ungültig ist, schlägt die Bereitstellung des API-Proxys fehl. Das gültige Format ist yyyy-MM-dd HH:mm:ss, also das Datums- und Uhrzeitformat ISO 8601. Wenn beispielsweise die im <StartTime>-Element angegebene Zeit 7-16-2017 12:00:00 lautet, schlägt die Bereitstellung des API-Proxys fehl.
StartTimeNotSupported Wenn das <StartTime>-Element angegeben ist, dessen Kontingenttyp nicht calendar ist, schlägt die Bereitstellung des API-Proxys fehl. Das <StartTime>-Element wird nur für den calendar-Kontingenttyp unterstützt. Wenn beispielsweise für das type-Attribut im <Quota>-Element der Wert flexi oder rolling window festgelegt ist, schlägt die Bereitstellung des API-Proxys fehl.
InvalidTimeUnitForDistributedQuota Ist das <Distributed>-Element auf true und das <TimeUnit>-Element auf second gesetzt, so schlägt die Bereitstellung des API-Proxys fehl. Die Zeiteinheit second ist für verteilte Kontingente unzulässig.
InvalidSynchronizeIntervalForAsyncConfiguration Ist der für das <SyncIntervalInSeconds>-Element im <AsynchronousConfiguration>-Element in einer Quota-Richtlinie angegebene Wert kleiner als null, so schlägt die Bereitstellung des API-Proxys fehl.
InvalidAsynchronizeConfigurationForSynchronousQuota Wenn der Wert des <AsynchronousConfiguration>-Elements in einer Quota-Richtlinie auf true gesetzt wird, aber auch eine asynchrone Konfiguration mithilfe des <AsynchronousConfiguration>-Elements vorliegt, dann wird die Bereitstellung des API-Proxy schlägt fehl.

Fehlervariablen

Diese Variablen werden festgelegt, wenn die Richtlinie einen Fehler auslöst. Weitere Informationen finden sich unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. ratelimit.QT-QuotaPolicy.failed = true

Beispiel für eine Fehlerantwort

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

Beispiel für eine Fehlerregel

<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>

Schemas

Weitere Informationen

ResetQuota-Richtlinie

SpikeArrest-Richtlinie

Kontingente und Spike Arrest-Richtlinien vergleichen