SpikeArrest-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Die SpikeArrest-Richtlinie schützt mit dem Element <Rate> vor Trafficanstieg. Dieses Element drosselt die Anzahl der Anfragen, die von einem API-Proxy verarbeitet und an ein Backend gesendet werden, um Leistungsverzögerungen und Ausfallzeiten zu verhindern.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Unterschied zwischen SpikeArrest- und Kontingentrichtlinie

Die Kontingentrichtlinie konfiguriert die Anzahl der Anfragenachrichten, die eine Client-Anwendung im Laufe einer Stunde, eines Tages, einer Woche oder eines Monats an eine API senden kann. Die Kontingentrichtlinie erzwingt Nutzungsbeschränkungen für Clientanwendungen, die einen verteilten Zähler zur Verfügung stellen, der eingehende Anfragen erhöht.

Verwenden Sie Kontingente, um Geschäftsverträge oder SLAs mit Entwicklern und Partnern zu erzwingen, anstatt für die operative Trafficverwaltung. SpikeArrest schützt vor plötzlichen Spitzen im API-Traffic. Siehe auch Kontingente und SpikeArrest-Richtlinien vergleichen.

Videos

In diesen Videos werden Anwendungsfälle für diese Richtlinie behandelt:

Element <SpikeArrest>

Definiert die SpikeArrest-Richtlinie.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Beispiele

Die folgenden Beispiele zeigen Möglichkeiten, wie Sie die SpikeArrest-Richtlinie verwenden können:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

curl https://my-api-endpoint.net/price -H 'runtime_rate:30ps'

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <SpikeArrest> beschrieben.

<DisplayName>

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

Das Element <DisplayName> ist für alle Richtlinien gleich.

Das <DisplayName>-Element verwendet die folgende Syntax:

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<Identifier>

Hier können Sie auswählen, wie die Anfragen gruppiert werden, sodass die SpikeArrest-Richtlinie basierend auf einem Element in der eingehenden Anfrage angewendet werden kann. Sie können beispielsweise Ratenbeschränkungen nach Entwickler-ID erzwingen. In diesem Fall wird für alle Anfragen, die von den Apps eines bestimmten Entwicklers gesendet werden, ein gemeinsamer SpikeArrest-Zähler verwendet. Alternativ können Sie ein Ratenlimit nach Client-ID erzwingen. In diesem Fall unterliegt jede Client-App einem separaten Ratenlimitzähler. Sie können auch auf eine Variable verweisen, die Ihr Proxy zuvor festgelegt hat. Diese Variable kann mehrere Faktoren kombinieren, z. B. die Client-ID und die IP-Adresse des Clients.

Wird in Verbindung mit dem Element <MessageWeight> für eine genauere Steuerung der Anfragedrosselung verwendet.

Wenn Sie das Element <Identifier> leer lassen, wird für alle Anfragen an diesen API-Proxy eine Ratenbegrenzung erzwungen.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

Dieses Element wird auch in diesem Apigee-Communitybeitrag behandelt.

<MessageWeight>

Gibt die für die aktuelle Nachricht definierte Gewichtung an. Die Nachrichtengewichtung ändert die Auswirkungen einer einzelnen Anfrage auf die Berechnung der SpikeArrest-Rate. Die Nachrichtengewichtung kann eine beliebige Ablaufvariable sein, z. B. ein HTTP-Header, Abfrageparameter, Formularparameter oder Inhalt des Nachrichtentexts. Normalerweise würden Sie jedoch keine Variable verwenden, die direkt aus der eingehenden Anfrage abgeleitet wird. Stattdessen verwenden Sie eine Variable, die ein benutzerdefiniertes Attribut für ein API-Produkt oder für die Clientanwendung darstellt. Sie können auch benutzerdefinierte Variablen verwenden, die mit dynamischen Werten über die JavaScript-Richtlinie oder die AssignMessage-Richtlinie festgelegt werden. In allen Fällen muss der Wert eine positive Ganzzahl ungleich Null sein.

Wird in Verbindung mit <Identifier> verwendet, um Anfragen von bestimmten Clients oder Anwendungen drosseln zu können.

Wenn der SpikeArrest <Rate> beispielsweise 10pm ist und der Proxy eine Variable verwendet, die den Wert 2 für die Nachrichtengewichtung enthält, sind für die angegebene Kennung nur 5 Nachrichten pro Minute zulässig, da jede Anfrage als 2 zählt.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Default-Weight-1">
  <Rate>1000pm</Rate>
  <Identifier ref="client_id" />
  <!-- omit <MessageWeight/> to use a default weight of 1 -->
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

<Rate>

Gibt die Rate an, mit der die Trafficspitzen (oder Bursts) durch Begrenzung der Anzahl der Anfragen pro Minute oder pro Sekunde eingeschränkt werden. Sie können dieses Element auch zusammen mit <Identifier> und <MessageWeight> verwenden, um den Traffic während der Laufzeit reibungslos zu drosseln. Verwenden Sie das Element <UseEffectiveCount>, um den von der Richtlinie verwendeten Algorithmus für die Ratenbegrenzung festzulegen.

Informationen zu den maximalen Ratenbegrenzungen, die Sie angeben können, finden Sie auf der Seite „Limits“ im Abschnitt zu SpikeArrest.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

<Rate ref="request.header.custom_rate">1pm</Rate>

<UseEffectiveCount>

Bei diesem Element können Sie zwischen unterschiedlichen SpikeArrest-Algorithmen wählen, indem Sie den Wert auf true oder false setzen, wie unten erläutert:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

In der folgenden Tabelle werden die Attribute des <UseEffectiveCount> -Elements beschrieben:

Ablaufvariablen

Beim Ausführen einer SpikeArrest-Richtlinie werden die folgenden Ablaufvariablen ausgefüllt:

Weitere Informationen finden Sie unter Referenz zu Ablaufvariablen.

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.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiel für eine Fehlerantwort

Im Folgenden sehen Sie ein Beispiel für eine Fehlerantwort:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Beispiel für eine Fehlerregel

Unten sehen Sie ein Beispiel für eine Fehlerregel zum Verarbeiten eines SpikeArrestViolation-Fehlers:

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

Der aktuelle HTTP-Statuscode zum Überschreiten einer Ratenbegrenzung, die von einer Kontingent- oder SpikeArrest-Richtlinie festgelegt wurde, lautet 429 (Zu viele Anfragen).

Schemas

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Weitere Informationen

• Kontingentrichtlinie: Kontingentrichtlinie zum Beschränken des Traffics auf einzelne Clients
• Ratenbegrenzung für eine Übersicht über Ratenbegrenzungen
• Kontingente und SpikeArrest-Richtlinien vergleichen