Règle SpikeArrest

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

La règle SpikeArrest protège contre les surcharges de trafic à l'aide de l'élément <Rate>. Cet élément limite le nombre de requêtes traitées par un proxy d'API et envoyées à un backend, ce qui protège contre les délais de latence et les temps d'arrêt.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Différence entre SpikeArrest et Quota

La règle de quota configure le nombre de messages de requête qu'une application cliente est autorisée à envoyer à une API pendant une heure, un jour, une semaine ou un mois. La règle de quota applique des limites de consommation aux applications clientes en alimentant un compteur distribué du nombre de requêtes entrantes.

Utilisez le quota pour appliquer des contrats d'entreprise ou des contrats de niveau de service vis-à-vis de développeurs et de partenaires, plutôt que pour la gestion du trafic opérationnel. Utilisez SpikeArrest comme protection contre les pics soudains du trafic de l'API. Consultez également la section Comparer les règles de quota et de pics.

Vidéos

Ces vidéos présentent les cas d'utilisation de cette règle :

Élément <SpikeArrest>

Définit la règle SpikeArrest.

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

This element has the following attributes that are common to all policies:

Exemples

Les exemples suivants illustrent certaines des méthodes d'utilisation de la règle 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>

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

Référence d'élément enfant

Cette section décrit les éléments enfants de <SpikeArrest>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

L'élément <DisplayName> utilise la syntaxe suivante :

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

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<Identifier>

Elle vous permet de choisir comment regrouper les requêtes afin de pouvoir appliquer la règle SpikeArrest en fonction d'un élément de la requête entrante. Par exemple, vous pouvez appliquer des limites de débit par ID de développeur, auquel cas toutes les requêtes envoyées par les applications appartenant à un développeur particulier partageront un seul nombre SpikeArrest. Vous pouvez également appliquer une limite de fréquence par ID client. Dans ce cas, chaque application cliente sera soumise à un compteur de limite de fréquence distinct. Vous pouvez également faire référence à une variable que votre proxy a définie précédemment. Cette variable peut combiner plusieurs facteurs, par exemple l'ID client et l'adresse IP du client.

Utilisez cette option conjointement avec l'élément <MessageWeight> pour un contrôle plus précis de la limitation du nombre de requêtes.

Si vous laissez l'élément <Identifier> vide, une limite de débit est appliquée à toutes les requêtes adressées à ce proxy d'API.

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

Le tableau suivant décrit les attributs de <Identifier> :

Ce problème est également abordé dans ce post destiné à la communauté Apigee.

<MessageWeight>

Indique la pondération définie pour le message actuel. La pondération des messages modifie l'impact d'une requête unique sur le calcul du taux SpikeArrest. La pondération du message peut être n'importe quelle variable de flux, telle qu'un en-tête HTTP, un paramètre de requête, un paramètre de formulaire ou le contenu du corps du message. Toutefois, vous n'utiliserez normalement pas de variable directement dérivée de la requête entrante. Vous devez utiliser une variable qui représente un attribut personnalisé sur un produit d'API ou sur l'application cliente. Vous pouvez également utiliser des variables personnalisées définies avec des valeurs dynamiques à l'aide de la règle JavaScript ou de la règle AssignMessage. Dans tous les cas, la valeur doit être un entier positif non nul.

Utilisez le poids conjointement avec <Identifier> pour limiter davantage les requêtes de clients ou d'applications spécifiques.

Par exemple, si le <Rate> de SpikeArrest est de 10pm et que le proxy utilise une variable qui contient la valeur 2 pour la pondération du message, seuls cinq messages par minute seront autorisés pour l'identifiant donné, car chaque requête compte pour deux.

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

Le tableau suivant décrit les attributs de <MessageWeight> :

<Rate>

Indique le débit limite des pics de trafic (ou d'utilisation intensive) en définissant le nombre de requêtes autorisées par minute ou par seconde. Vous pouvez utiliser cet élément conjointement avec <Identifier> et <MessageWeight> afin de limiter de manière fluide le trafic au moment de l'exécution avec un contrôle précis. Utilisez l'élément <UseEffectiveCount> pour définir l'algorithme de limitation du débit utilisé par la règle.

Consultez la section SpikeArrest de la page "Limites" pour connaître les limites de débit maximales que vous pouvez spécifier.

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

Le tableau suivant décrit les attributs de <Rate> :

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

<UseEffectiveCount>

Cet élément vous permet de choisir entre des algorithmes SpikeArrest distincts en définissant la valeur sur true ou false, comme expliqué ci-dessous :

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

Le tableau suivant décrit les attributs de l'élément <UseEffectiveCount> :

Variables de flux

Lorsqu'une règle SpikeArrest est exécutée, les variables de flux suivantes sont renseignées :

Pour en savoir plus, consultez la documentation de référence sur les variables de flux.

Informations de référence sur les erreurs

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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>

Le code d'état HTTP actuel pour le dépassement d'une limite de débit définie par une règle Quota ou Spike Arrest est "429" (trop de requêtes).

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Articles associés

• Règle de quota : règle de quotas limitant le trafic sur les clients individuels
• Limitation du débit pour consulter une présentation de la limitation du débit
• Comparer les règles Quota et SpikeArrest