Règle SpikeArrest

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

Icône d&#39;arrêt de Spike dans l&#39;interface utilisateur 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.

É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 N/A
É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 Spike Arrest (Arrêt des pics) à votre dans l'interface utilisateur Edge:

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

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

Attribut Par défaut Obligatoire ? Description
name N/A 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éfini sur "false" pour renvoyer une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Défini sur "true" pour que l'exécution du flux se poursuive même après l'échec d'une règle.
enabled vrai Facultatif Défini sur "true" pour appliquer la règle. Défini 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>
</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>
</SpikeArrest>

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

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

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
Requis ? 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 Aucune

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

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

Attribut Description Par défaut Présence
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

Cet élément est également abordé dans le post destiné à la communauté Apigee suivant : http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

Indique la pondération définie pour chaque message. La pondération du message modifie l'impact d'une même demande pour le calcul du taux d'arrêt des pics. 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 qu'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" />
</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 Présence 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. Valeur ND

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

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>
</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>
</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 Présence 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 un en-tête "custom_rate", le débit du proxy d'API sera d'une requête par minute pour tous les clients. Si le client transmet un en-tête "custom_rate", la limite de débit est de 10 requêtes par seconde pour tous les clients du 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 débits personnalisés selon le type de client.

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>

Distribue le nombre d'arrêts des pics sur les processeurs de messages lorsque vous utilisez l'autoscaling groupes.

Syntaxe

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

Exemple 1

L'exemple suivant définit <UseEffectiveCount> sur "true" :

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

L'élément <UseEffectiveCount> est facultatif. La valeur par défaut est false lorsque l'élément est omis de votre règle Spike Arrest.

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 Présence
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. Non disponible Facultatif

L'effet de <UseEffectiveCount> dépend de sa valeur:

  • true: la limite du taux de pics d'un MP est <Rate> divisé par le nombre actuel de MP dans la même série d'annonces. La limite d'agrégation est la valeur sur <Rate>. Lorsque des MP sont ajoutés (ou supprimés de façon dynamique), leur pic individuel les limites de débit augmentent (ou diminuent), mais la limite globale reste la même.
  • false (il s'agit de la valeur par défaut en cas d'omission): la limite du taux de pics de chaque MP est simplement la valeur de son <Rate>. La limite d'agrégation est la somme des taux de tous les MP. Lorsque des MP sont ajoutés (ou supprimés), les limites de taux de pic individuelles restent les mêmes, mais la limite globale augmente (ou diminuer).

Le tableau suivant montre l'effet de <UseEffectiveCount> sur la limite de débit effectif de chaque MP:

Valeur de <UseEffectiveCount>
false false false true true true
Nombre de députés 8 4 2 8 4 2
Valeur de <Rate> 10 10 10 40 1 40
Taux effectif par MP 10 10 10 5 10 20
Limite d'agrégation 80 40 20 40* 40* 40*
* Identique à <Rate>.

Dans cet exemple, notez que lorsque le nombre de MP passe de 4 à 2, et que <UseEffectiveCount> est de false, le taux effectif par MP reste le même (à 10). Mais lorsque <UseEffectiveCount> est de true, le taux effectif par MP passe de 10 à 20 lorsque le nombre de MP passe de 4 à 2.

Variables de flux

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

Variable Type Permission 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 ainsi que les variables d'erreur qui sont définis par Edge 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.

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 Spike Arrest. Cet élément est obligatoire et permet de spécifier le taux d'arrêt de pic 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 a été dépassée.

<ph type="x-smartling-placeholder">

Erreurs de déploiement

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

Nom de l'erreur Cause Corriger
InvalidAllowedRate Si le taux d'arrêt de pic spécifié dans l'élément <Rate> de la règle Spike Arrest n'est pas un entier ou si le taux ne comporte pas ps ou pm comme suffixe, alors 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 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 :

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

Code d'état HTTP actuel du dépassement d'une limite de débit définie par une règle Quota ou Spike Arrest est 429 (requêtes excessives). Pour remplacer le code d'état HTTP par 500 (Erreur interne du serveur), définissez la propriété features.isHTTPStatusTooManyRequestEnabled à false avec le API de mise à jour des propriétés de l'organisation

<ph type="x-smartling-placeholder">

Exemple :

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

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