Règle SpikeArrest

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

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.

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

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

Exemples

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

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

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

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

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

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 des messages modifie l'impact d'une requête unique sur le calcul du taux Spike Arrest. 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.

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

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

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

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

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

<UseEffectiveCount>

Distribue vos mesures de Spike Arrest entre les processeurs de messages (MP) lorsque vous utilisez des groupes d'autoscaling.

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

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.

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

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

• true: la limite de taux de pic d'un MP correspond à <Rate> divisé par le nombre actuel de MP dans le même pod. La limite globale est la valeur de <Rate>. Lorsque des MP sont ajoutés (ou supprimés) de manière dynamique, leurs limites de taux de pic individuels augmentent (ou diminuent), mais la limite globale reste la même.
• false (valeur par défaut si elle est omise): la limite de taux de pic de chaque MP correspond simplement à la valeur de son <Rate>. La limite globale correspond à la somme des tarifs de tous les MP. Lorsque des MP sont ajoutés (ou supprimés), leurs limites individuelles de taux de pic restent les mêmes, mais la limite globale augmente (ou diminue).

Le tableau suivant indique l'impact de <UseEffectiveCount> sur la limite de débit effective de chaque MP:

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

Variables de flux

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

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

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 (Mettre à jour les propriétés de l'organisation).

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

• 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
• Exemples d'utilisation de proxys d'API