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 :

Utilité

Comparer les règles de quotas

Élément <SpikeArrest>

Définit la règle SpikeArrest.

Valeur par défaut	Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ?	Facultatif
Type	Objet complexe
Élément parent	Non disponible
Éléments enfants	<Identifier> <MessageWeight> <Rate> (Obligatoire) <UseEffectiveCount>

Syntaxe

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

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

Règle par défaut

L'exemple suivant présente les paramètres par défaut lorsque vous ajoutez une règle SpikeArrest à votre flux dans l'interface utilisateur :

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

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
name	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError	faux	Facultatif	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
enabled	true	Facultatif	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async	faux	Obsolète	Cet attribut est obsolète.

Exemples

Les exemples suivants illustrent certaines des méthodes d'utilisation la règle SpikeArrest :

Exemple 1

Dans l'exemple suivant, la fréquence est définie sur cinq requêtes par seconde :

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

Cet exemple de règle autorise un maximum de 5 requêtes par seconde. Par lissage, il est appliqué avec un maximum d'une requête pour chaque intervalle de 200 millisecondes (1 000/5).

Exemple 2

Dans l'exemple suivant, le débit est défini sur 12 requêtes par minute :

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Cet exemple de règle autorise un maximum de 12 requêtes par minute à raison d'une requête toutes les cinq secondes (60/12). S'il y a plusieurs requêtes dans l'intervalle de 5 secondes, ces requêtes sont autorisées (aucun lissage) à condition que le nombre de requêtes soit inférieur à la limite de débit configurée de 12 par minute.

Exemple 3

L'exemple suivant limite le nombre de requêtes à 12 par minute (une requête autorisée toutes les cinq secondes, ou 60 / 12) :

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

De plus, l'élément <MessageWeight> accepte une valeur personnalisée (l'en-tête weight) qui ajuste les pondérations des messages pour des applications ou des clients spécifiques. Cela permet de mieux contrôler la limitation du débit pour les entités identifiées avec l'élément <Identifier>.

Exemple 4

L'exemple suivant demande à SpikeArrest de rechercher une valeur d'exécution définie via la requête transmise en tant que variable de flux request.header.runtime_rate :

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

La valeur de la variable de flux doit être au format intpm ou intps.

Pour essayer cet exemple, exécutez une requête semblable à celle-ci :

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

Conseil : Consultez la section Comment puis-je utiliser les produits d'API pour définir des limites d'arrêt des pics ? qui explique comment définir un taux SpikeArrest à l'aide de variables personnalisées définies dans un produit d'API.

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.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type	Chaîne
Élément parent	<PolicyElement>
Éléments enfants	Aucun

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

Syntaxe

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

Exemple

<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 du client. Par exemple, vous pouvez regrouper les requêtes par ID de développeur, auquel cas les requêtes de chaque développeur compteront pour leur propre débit SpikeArrest, et non toutes les requêtes adressées au proxy.

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.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	<SpikeArrest>
Éléments enfants	Aucun

Syntaxe

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

Exemple 1

L'exemple suivant applique la règle SpikeArrest par ID de développeur :

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

Attribut	Description	Par défaut	Presence
ref	Identifie la variable selon laquelle SpikeArrest regroupe les requêtes entrantes. Vous pouvez utiliser n'importe quelle variable de flux pour indiquer un client unique, telles que celle disponible dans la règle VerifyAPIKey. Vous pouvez également définir des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage.	n/a	Obligatoire

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

<MessageWeight>

Indique la pondération définie pour chaque message. 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. Vous pouvez également utiliser des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage.

Celles-ci sont à utiliser 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 si une application envoie des requêtes avec une pondération de 2, seuls cinq messages par minute sont autorisés en provenance de ce client, car chaque requête compte pour deux.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Entier
Élément parent	<SpikeArrest>
Éléments enfants	Aucun

Syntaxe

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

Exemple 1

L'exemple suivant limite le nombre de requêtes à 12 par minute (une requête autorisée toutes les cinq secondes, ou 60 / 12) :

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

Dans cet exemple, <MessageWeight> accepte une valeur personnalisée (l'en-tête weight dans la requête) qui ajuste les pondérations des messages pour des clients spécifiques. Cela permet de mieux contrôler la limitation du débit pour les entités identifiées avec l'élément <Identifier>.

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

Attribut	Description	Presence	Par défaut
ref	Identifie la variable de flux qui contient la pondération du message pour le client spécifique. Il peut s'agir de n'importe quelle variable de flux, telle qu'un paramètre de requête HTTP, un en-tête ou le contenu du corps du message. Pour en savoir plus, consultez la documentation de référence sur les variables de flux. Vous pouvez également définir des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage.	Obligatoire	N/A

<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 également utiliser cet élément conjointement avec <Identifier> et <MessageWeight> afin de limiter de manière fluide le trafic au moment de l'exécution en acceptant les valeurs du client. Utilisez l'élément <UseEffectiveCount> pour définir l'algorithme de limitation du débit utilisé par la règle.

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

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Entier
Élément parent	<SpikeArrest>
Éléments enfants	Aucun

Syntaxe

Vous pouvez spécifier les débits de l'une des manières suivantes :

• Un débit statique que vous spécifiez comme corps de l'élément <Rate>
• Une valeur variable qui peut être transmise par le client ; identifiez le nom de la variable de flux à l'aide de l'attribut ref

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

Les valeurs de débit valides (définies en tant que valeur variable ou dans le corps de l'élément) doivent respecter le format suivant :

• intps (nombre de requêtes par seconde, lissé sur des intervalles de quelques millisecondes)
• intpm (nombre de requêtes par minute, lissé sur des intervalles de quelques secondes)

La valeur de int doit être un entier positif non nul.

Exemple 1

Dans l'exemple suivant, le débit est défini sur cinq requêtes par seconde :

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

La règle lisse le débit pour obtenir une requête autorisée toutes les 200 millisecondes (1 000 / 5).

Exemple 2

Dans l'exemple suivant, le débit est défini sur 12 requêtes par minute :

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Cet exemple de règle lisse le débit pour obtenir une requête autorisée toutes les cinq secondes (60 / 12).

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

Attribut	Description	Presence	Par défaut
ref	Identifie une variable de flux qui spécifie le débit. Il peut s'agir de n'importe quelle variable de flux, telle qu'un paramètre de requête HTTP, un en-tête, le contenu du corps d'un message ou une valeur telle qu'une KVM. Pour en savoir plus, consultez la documentation de référence sur les variables de flux. Vous pouvez également utiliser des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage. Si vous définissez à la fois ref et le corps de cet élément, la valeur de ref est appliquée et est prioritaire lorsque la variable de flux est définie dans la requête. (L'inverse est vrai lorsque la variable identifiée dans ref n'est pas définie dans la requête.) Exemple : <Rate ref="request.header.custom_rate">1pm</Rate> Dans cet exemple, si le client ne transmet pas d'en-tête custom_rate, le taux du proxy d'API est d'une requête par minute pour tous les clients. Si le client transmet un en-tête custom_rate, la limite du débit passe à 10 requêtes par seconde pour tous les clients sur le proxy, jusqu'à ce qu'une requête sans en-tête custom_rate soit envoyée. Vous pouvez utiliser <Identifier> pour regrouper les requêtes afin d'appliquer des taux personnalisés à différents types de clients. Si vous spécifiez une valeur pour ref, mais que vous ne définissez pas le débit dans le corps de l'élément <Rate> et que le client ne transmet pas de valeur, la règle SpikeArrest génère une erreur.	Facultatif	n/a

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

true

Si la valeur est true, SpikeArrest est distribué dans une région. Cela signifie que le décompte des requêtes est synchronisé entre les processeurs de messages (MP) d'une même région. En outre, un algorithme de limitation du débit "à fenêtre glissante" est utilisé. Cet algorithme fournit un comportement de limitation de débit cohérent et ne "lisse" pas le nombre de requêtes entrantes pouvant être envoyées au backend. Si une rafale de requêtes est envoyée sur une courte période, elles sont autorisées tant qu'elles ne dépassent pas la limitation de débit configurée, telle que définie dans l'élément <Rate>. Exemple :

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

false (valeur par défaut)

Si la valeur est false (valeur par défaut), la règle SpikeArrest utilise un algorithme "token bucket" qui lisse les pics de trafic en divisant la limite de débit que vous définissez en intervalles plus courts. L'inconvénient de cette approche est que plusieurs requêtes légitimes qui arrivent sur une courte période peuvent être refusées.

Par exemple, supposons que vous saisissiez un débit de 30 pm (30 requêtes par minute). Lors des tests, on pourrait imaginer envoyer 30 requêtes en une seconde, à condition qu'elles arrivent dans la minute qui suit. Mais ce n'est pas ainsi que la règle s'applique. À bien y réfléchir, 30 requêtes en une seconde pourraient être considérées comme un mini pic dans certains environnements.

• Les débits par minute sont lissés pour obtenir un nombre de requêtes complètes autorisées par intervalles exprimés en secondes.
  

  Par exemple, un taux de 30 pm est lissé de la manière suivante :
  60 secondes (une minute) / 30 = 2 secondes, soit une requête autorisée toutes les deux secondes. Une seconde requête dans un intervalle de deux secondes échouera. Une 31e requête dans un intervalle d'une minute échouera également.

• Les débits par seconde sont lissés pour obtenir un nombre de requêtes complètes autorisées par intervalles exprimés en millisecondes.

  Par exemple, un débit de 10 ps est lissé comme suit :
  1 000 millisecondes (1 seconde) / 10 ps = 100 millisecondes d'intervalles ou une requête autorisée toutes les 100 millisecondes. Une deuxième requête dans un intervalle de 100 ms échouera. En outre, une 11e requête dans un intervalle d'une seconde échouera.

Remarque : En cas de lissage du débit, le nombre de requêtes est toujours un nombre entier supérieur à zéro. Le lissage n'implique jamais de calcul de fractions de requêtes.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<SpikeArrest>
Éléments enfants	Aucun

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

Attribut	Description	Par défaut	Presence
ref	Identifie la variable contenant la valeur de <UseEffectiveCount>. Il peut s'agir de n'importe quelle variable de flux, telle qu'un paramètre de requête HTTP, un en-tête ou le contenu du corps du message. Pour en savoir plus, consultez la documentation de référence sur les variables de flux. Vous pouvez également définir des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage.	n/a	Facultatif

Variables de flux

Lorsqu'une règle SpikeArrest est exécutée, la variable de flux suivante est renseignée :

Variable	Type	Autorisation	Description
ratelimit.policy_name.failed	Booléen	En lecture seule	Indique si la règle a échoué (true ou false).

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

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Code d'erreur	État HTTP	Cause	Corriger
policies.ratelimit.FailedToResolveSpikeArrestRate	500	Cette erreur se produit si la référence à la variable contenant le paramètre de taux dans l'élément <Rate> ne peut pas être résolue en une valeur comprise dans la règle SpikeArrest. Cet élément est obligatoire et permet de spécifier le taux d'arrêt des pics sous la forme intpm ou intps.
policies.ratelimit.InvalidMessageWeight	500	Cette erreur se produit si la valeur spécifiée pour l'élément <MessageWeight> via une variable de flux n'est pas valide (valeur non entière).
policies.ratelimit.SpikeArrestViolation	429	La limite de débit est dépassée.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Nom de l'erreur	Cause	Corriger
InvalidAllowedRate	Si le taux d'arrêt des pics spécifié dans l'élément <Rate> de la règle SpikeArrest n'est pas un entier, ou si le taux ne contient pas ps ou pm en tant que suffixe, le déploiement du proxy d'API échoue.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	ratelimit.SA-SpikeArrestPolicy.failed = true

Exemple de réponse d'erreur

Vous trouverez ci-dessous un exemple de réponse d'erreur :

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

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

Exemple de règle de défaillance

Vous trouverez ci-dessous un exemple de règle d'erreur pour gérer une erreur SpikeArrestViolation :

<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). Pour remplacer le code d'état HTTP par "500" (erreur interne du serveur), définissez la propriété features.isHTTPStatusTooManyRequestEnabled sur false à l'aide de l'API Update organization properties.

Attention : Lors de la mise à jour des propriétés, vous devez transmettre toutes les propriétés existantes à l'API, même si elles ne sont pas modifiées. Si vous laissez des propriétés en dehors de la charge utile de l'appel d'API Update organization properties, celles-ci seront supprimées. Pour obtenir la liste actuelle des propriétés de l'environnement, utilisez l'API Get organization.

Si vous tentez de définir une propriété, mais que la valeur de la propriété mise à jour n'est pas renvoyée dans la charge utile de la réponse, cela signifie que la propriété doit être définie par un utilisateur disposant du rôle sysadmin. Contactez l'assistance Apigee pour modifier une valeur de propriété nécessitant le rôle sysadmin.

Exemple :

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

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