SpikeArrest-Richtlinie

Sie lesen gerade die Dokumentation zu Apigee Edge.
Zur Dokumentation zu Apigee X info

Die Spike Arrest-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 Back-End gesendet werden, um Leistungsverzögerungen und Ausfallzeiten zu verhindern.

Element <SpikeArrest>

Definiert die Spike Arrest-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>true</UseEffectiveCount>
</SpikeArrest>

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

Beispiele

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

curl http://myorg-myenv.apigee.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 Spike Arrest-Richtlinie basierend auf dem Client angewendet werden kann. Sie können beispielsweise Anfragen nach Entwickler-ID gruppieren. In diesem Fall werden die Anfragen jedes Entwicklers auf die eigene Spike Arrest-Rate und nicht auf alle Anfragen an den Proxy angerechnet.

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

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

Dieses Element wird auch im folgenden Apigee-Communitybeitrag diskutiert: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

Gibt die für jede Nachricht definierte Gewichtung an. Die Nachrichtengewichtung ändert die Auswirkungen einer einzelnen Anfrage auf die Berechnung der Spike Arrest-Rate. Die Nachrichtengewichtung kann eine beliebige Ablaufvariable sein, z. B. ein HTTP-Header, Abfrageparameter, Formularparameter oder Inhalt des Nachrichtentexts. Sie können auch benutzerdefinierte Variablen mithilfe der JavaScript-Richtlinie oder der AssignMessage-Richtlinie verwenden.

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

Wenn der Spike Arrest <Rate> beispielsweise 10pm ist und eine Anwendung Anfragen mit einer Gewichtung von 2 sendet, sind von diesem Client nur fünf Nachrichten pro Minute zulässig, weil jede Anfrage als 2 zählt.

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</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, indem Sie Werte vom Client akzeptieren.

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

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

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

<UseEffectiveCount>

Verteilt Ihre SpikeArrest-Zähler auf Nachrichtenprozessoren (Message Processors, MPs), wenn Sie Autoscaling-Gruppen verwenden.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Das <UseEffectiveCount>-Element ist optional. Der Standardwert ist false, wenn das Element in Ihrer Spike Arrest-Richtlinie nicht enthalten ist.

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

Die Wirkung von <UseEffectiveCount> hängt von seinem Wert ab:

• true: Das Spike-Ratenlimit eines MP ist die <Rate> geteilt durch die aktuelle Anzahl von MPs im selben Pod. Das aggregierte Limit ist der Wert von <Rate>. Wenn MPs dynamisch hinzugefügt oder entfernt werden, erhöhen oder verringern sich die individuellen Ratenbegrenzungen für Spitzen, die aggregierte Begrenzung bleibt jedoch gleich.
• false: Das Limit für die Spike-Rate jedes MP ist einfach der Wert von <Rate>. Das aggregierte Limit ist die Summe der Raten aller MPs. Wenn MPs hinzugefügt oder entfernt werden, bleiben ihre individuellen Ratenbegrenzungen für Spitzen gleich, aber die aggregierte Begrenzung wird erhöht oder verringert.

Die SpikeArrest-Richtlinie verwendet einen Algorithmus des Typs Token-Bucket, der die Traffic-Spitzen glättet, indem die von Ihnen angegebene Ratenbegrenzung in kleinere Intervalle aufgeteilt wird. Ein Nachteil dieses Ansatzes ist, dass mehrere legitime Anfragen, die über einen kurzen Zeitraum eingehen, potenziell abgelehnt werden können.

Angenommen, Sie geben eine Rate von 30pm (30 Anfragen pro Minute) ein. Beim Testen können Sie 30 Anfragen innerhalb einer Sekunde senden, sofern sie innerhalb einer Minute gesendet wurden. Aber das wird nicht durch die Richtlinie erzwungen. Wenn Sie darüber nachdenken, können 30 Anfragen innerhalb eines Zeitraums von 1 Sekunde in einigen Umgebungen als kleiner Anstieg angesehen werden.

• Minutenraten werden in vollständige Anfragen geglättet, die in Intervallen von Sekunden zulässig sind.
  

  Zum Beispiel wird 30pm so geglättet:
  60 Sekunden (1 Minute) / 30pm = 2-Sekunden-Intervalle oder alle 2 Sekunden ist 1 Anfrage zulässig. Eine zweite Anfrage innerhalb von 2 Sekunden schlägt fehl. Außerdem schlägt die 31. Anfrage innerhalb einer Minute fehl.

• Sekundenraten werden in vollständige Anfragen geglättet, die in Intervallen von Millisekunden zulässig sind.

  10ps werden z. B. so geglättet:
  1.000 Millisekunden (1 Sekunde) / 10ps = 100-Millisekunden-Intervalle bzw. 1 Anfrage alle 100 Millisekunden. Eine zweite Anfrage innerhalb von 100ms schlägt fehl. Außerdem schlägt eine 11. Anfrage innerhalb einer Sekunde fehl.

In der folgenden Tabelle sehen Sie die Auswirkungen von <UseEffectiveCount> auf das effektive Ratenlimit der einzelnen MPs:

In diesem Beispiel sehen Sie, dass die effektive Rate pro MP gleich bleibt (bei 10), wenn die Anzahl der MPs von 4 auf 2 reduziert wird und <UseEffectiveCount> gleich false ist. Wenn <UseEffectiveCount> jedoch true ist, steigt der effektive Preis pro MP von 10 auf 20, wenn die Anzahl der MPs von 4 auf 2 sinkt.

Ablaufvariablen

Beim Ausführen einer Spike Arrest-Richtlinie wird die folgende Ablaufvariable ausgefüllt:

Weitere Informationen finden Sie unter Referenz zu Ablaufvariablen.

Fehlerreferenz

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

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

Shown below is an example error response:

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

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

<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 Spike Arrest-Richtlinie festgelegt wurde, lautet 429 (Zu viele Anfragen). Wenn Sie den HTTP-Statuscode in 500 (Interner Serverfehler) ändern möchten, setzen Sie das Attribut features.isHTTPStatusTooManyRequestEnabled über die API Organisationsattribute aktualisieren auf false.

Beispiel:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

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
• Kontingent- und SpikeArrest-Richtlinien vergleichen
• Übungsbeispiele für API-Proxys