Règles de quotas

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

Quoi

Utilisez les règles de quotas pour configurer le nombre de messages de requête autorisés par un proxy d'API sur une période donnée, telle qu'une minute, une heure, un jour, une semaine ou un mois. Vous pouvez définir le même quota pour toutes les applications qui accèdent au proxy d'API, ou définir le quota en fonction des éléments suivants :

• Produit contenant le proxy d'API
• L'application qui demande l'API
• Le développeur de l'application
• De nombreux autres critères

N'utilisez pas de quota pour vous protéger contre les pics de trafic global. Utilisez pour cela la règle Spike Arrest. Consultez la section Règle d'arrêt des pics (Spike Arrest).

Vidéos

Les vidéos suivantes présentent la gestion des quotas à l'aide des règles de quotas :

Exemples

Ces exemples de codes de règles montrent comment définir le début et la fin d'une période de quota :

<Quota name="CheckQuota"> 
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

<Quota name="DeveloperQuota"> 
  <Identifier ref="verifyapikey.verify-api-key.client_id"/> 
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> 
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> 
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> 
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Identifier ref="request.queryparam.id"/>

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

À propos des règles de quotas

Un quota est une attribution de messages de requête qu'un proxy d'API peut traiter sur une période donnée (minute, heure, jour, semaine ou mois). La règle conserve les compteurs qui comptabilisent le nombre de requêtes reçues par le proxy d'API. Cette fonctionnalité permet aux fournisseurs d'API d'appliquer des limites sur le nombre d'appels d'API effectués par des applications sur un intervalle de temps donné. Les règles quotas vous permettent, par exemple, de limiter les applications à une requête par minute, ou à 10 000 requêtes par mois.

Par exemple, si un quota est défini sur 10 000 messages par mois, la limitation du débit commence après le 10 000e message. Peu importe si 10 000 messages ont été comptés le premier ou le dernier jour de cette période. Aucune requête supplémentaire n'est autorisée jusqu'à la réinitialisation automatique du compteur de quota à la fin de l'intervalle de temps spécifié ou jusqu'à ce qu'il soit explicitement réinitialisé à l'aide de la règle de réinitialisation du quota.

Une variation de quota, appelée SpikeArrest, empêche les pics de trafic (ou d'utilisation intensive) pouvant être causés par une augmentation soudaine de l'utilisation, des bugs clients ou des attaques malveillantes. Pour plus d'informations sur Spike Arrest, consultez la section Règle Spike Arrest.

Les quotas s'appliquent à chaque proxy d'API et ne sont pas répartis entre les proxys d'API. Par exemple, si vous avez trois proxys d'API dans un produit d'API, un quota unique n'est pas partagé entre les trois, même si les trois utilisent la même configuration de règle de quota.

Types de règles de quotas

Les règles de quotas acceptent plusieurs types de règles : par défaut, calendar, flexi et rollingwindow. Chaque type définit le démarrage et la réinitialisation du compteur de quotas, comme indiqué dans le tableau suivant :

Pour type="calendar", vous devez spécifier la valeur de <StartTime>.

La valeur du type rollingwindow n'est pas indiquée dans le tableau. Les quotas par fenêtre glissante fonctionnent en définissant la taille d'une "fenêtre", par exemple un intervalle d'une heure ou d'une journée. Lorsqu'une nouvelle requête arrive, la règle détermine si le quota a été dépassé au cours de la dernière "fenêtre".

Par exemple, vous définissez une fenêtre de deux heures qui autorise 1 000 requêtes. Une nouvelle requête est envoyée à 16h45.La règle calcule le quota pour la dernière heure (soit le nombre de requêtes depuis 14h45). Si la limite de quota n'a pas été dépassée au cours de cet intervalle de deux heures, la requête est autorisée.

Une minute plus tard, à 16h46, une autre requête arrive. La règle calcule maintenant le quota depuis 14h46 pour déterminer si la limite a été dépassée.

Pour le type rollingwindow, le compteur n'est jamais réinitialisé, mais il est recalculé à chaque requête.

Comprendre les compteurs de quotas

Par défaut, une règle de quota gère un compteur unique, quel que soit le nombre de fois que vous y faites référence dans un proxy d'API. Le nom du compteur de quota est basé sur l'attribut name de la règle.

Par exemple, vous créez une règle de quota nommée MyQuotaPolicy avec une limite de 5 requêtes et la placez sur plusieurs flux (Flux A, B et C) dans le proxy d'API. Même si elle est utilisée dans plusieurs flux, elle conserve un compteur unique mis à jour par toutes les instances de la règle :

• Flux A exécuté -> la règle MyQuotaPolicy est exécutée et son compteur = 1
• Flux B exécuté -> la règle MyQuotaPolicy est exécutée et son compteur = 2
• Flux A exécuté -> la règle MyQuotaPolicy est exécutée et son compteur = 3
• Flow C est exécuté -> la règle MyQuotaPolicy est exécutée et son compteur = 4
• Flux A exécuté -> la règle MyQuotaPolicy est exécutée et son compteur = 5

La requête suivante vers l'un des trois flux est rejetée, car le compteur de quota a atteint sa limite.

L'utilisation de la même règle de quota à plusieurs endroits dans un flux de proxy d'API, ce qui peut peut entraîner involontairement une expiration du quota plus rapide que prévu, est un anti-modèle décrit dans The Book of Apigee Edge Antipatterns (Le livre des antimodèles d'Apigee Edge).

Vous pouvez également définir plusieurs règles de quotas dans votre proxy d'API et utiliser une règle différente dans chaque flux. Chaque règle de quota conserve son propre compteur, en fonction de son attribut name.

Vous pouvez également utiliser les éléments <Class> ou <Identifier> de la règle de quota pour définir plusieurs compteurs uniques dans une seule règle. En utilisant ces éléments, une seule règle peut gérer différents compteurs en fonction de l'application qui envoie la requête, du développeur de l'application qui effectue la requête, d'un ID client ou d'un autre identifiant client, etc. Consultez les exemples ci-dessus pour en savoir plus sur l'utilisation des éléments <Class> ou <Identifier>.

Notation de l'heure

Tous les quotas de quotas sont définis sur le fuseau horaire du temps universel coordonné (UTC).

La notation de temps respecte la notation de date internationale standard définie par la norme internationale ISO 8601.

Les dates sont définies en année, mois et jour, au format suivant : YYYY-MM-DD. Par exemple, 2015-02-04 correspond au 4 février 2015.

L'heure de la journée se définit en heures, minutes et secondes au format suivant : hours:minutes:seconds. Par exemple, 23:59:59 représente l'heure une seconde avant minuit.

Notez que deux notations, 00:00:00 et 24:00:00, sont disponibles pour distinguer les deux représentations de minuit qui peuvent être associées à une date. Par conséquent, 2015-02-04 24:00:00 est la même date et la même heure que 2015-02-05 00:00:00. Ce dernier format est généralement la notation préférée.

Obtenir des paramètres de quota à partir de la configuration du produit d'API

Vous pouvez définir des limites de quota dans les configurations de produit de l'API. Ces limites ne s'appliquent pas automatiquement au quota. À la place, vous pouvez référencer des paramètres de quota du produit dans une règle de quota. Voici quelques avantages liés à la définition d'un quota sur le produit pour les règles de quota à référencer :

• Les règles de quota peuvent utiliser un paramètre uniforme pour tous les proxys d'API du produit d'API.
• Vous pouvez modifier l'environnement d'exécution du paramètre de quota d'un produit d'API, et les règles de quotas qui font référence à la valeur ont automatiquement des valeurs de quota mises à jour.

Pour plus d'informations sur l'utilisation des paramètres de quota d'un produit d'API, consultez l'exemple "Quotas dynamiques" ci-dessus.

Pour en savoir plus sur la configuration des produits d'API avec des limites de quota, consultez la page Créer des produits d'API.

Documentation de référence des éléments

Vous trouverez ci-dessous les éléments et les attributs que vous pouvez configurer sur cette règle. Notez que certaines combinaisons d'éléments s'excluent mutuellement ou ne sont pas obligatoires. Consultez les exemples pour une utilisation spécifique. Les variables verifyapikey.VerifyAPIKey.apiproduct.* ci-dessous sont disponibles par défaut lorsqu'une règle de validation de la clé API appelée "VerifyAPIKey" est utilisée pour vérifier la clé API de l'application dans la requête. Les valeurs des variables proviennent des paramètres de quota du produit d'API auquel la clé est associée, comme décrit dans la section Obtenir des paramètres de quota à partir de la configuration du produit d'API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Attributs <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Les attributs suivants sont spécifiques à cette règle.

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <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, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <Allow>

Spécifie le nombre maximal lié au quota. Si le compteur de la règle atteint cette limite, les appels suivants sont rejetés jusqu'à la réinitialisation du compteur.

Voici trois façons de définir l'élément <Allow> :

<Allow count="2000"/> 

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

Si vous spécifiez à la fois count et countRef, countRef obtient la priorité. Si countRef n'est pas renvoyé au moment de l'exécution, la valeur de count est utilisée.

Attributs

Élément <Allow>/<Class>

L'élément <Class> vous permet de conditionner la valeur de l'élément <Allow> en fonction de la valeur d'une variable de flux. Pour chaque tag enfant <Allow> différent de <Class>, la règle conserve un compteur différent.

Pour utiliser l'élément <Class>, spécifiez une variable de flux en spécifiant l'attribut ref dans le tag <Class>. Edge utilise ensuite la valeur de la variable de flux pour sélectionner l'un des tags enfants <Allow> afin de déterminer le nombre de règles autorisé. Edge met en correspondance la valeur de la variable de flux avec l'attribut class du tag <Allow>, comme indiqué ci-dessous :

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Dans cet exemple, le compteur de quota actuel est déterminé par la valeur du paramètre de requête time_variable transmis avec chaque requête. Cette variable peut avoir la valeur peak_time ou off_peak_time. Si le paramètre de requête contient une valeur non valide, la règle renvoie une erreur de non-respect du quota.

Attributs

Élément <Allow>/<Class>/<Allow>

L'élément <Allow> spécifie la limite d'un compteur de quota défini par l'élément <Class>. Pour chaque balise enfant <Allow> différente de <Class>, la règle conserve un compteur différent.

Exemple :

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Dans cet exemple, la règle relative aux quotas gère deux compteurs de quota nommés peak_time et off_peak_time.

Attributs

Élément <Interval>

Permet de spécifier un entier (par exemple, 1, 2, 5, 60, etc.) qui sera associé au TimeUnit que vous spécifiez (minute, heure, jour, semaine ou mois) pour déterminer une période pendant laquelle Edge calcule l'utilisation du quota.

Par exemple, un Interval de 24 avec une TimeUnit en hour signifie que le quota est calculé sur une période de 24 heures.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

Attributs

Élément <TimeUnit>

Permet de spécifier l'unité de temps applicable au quota.

Par exemple, un Interval de 24 avec une TimeUnit en hour signifie que le quota est calculé sur une période de 24 heures.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Attributs

Élément <StartTime>

Lorsque type est défini sur calendar,, la date et l'heure auxquelles le compteur de quota commence à comptabiliser, même si des requêtes ont été reçues par des applications.

Vous devez fournir un identifiant StartTime explicite lorsque type est explicitement défini sur calendar,, vous ne pouvez pas utiliser une référence à une variable de flux. Si vous spécifiez une valeur StartTime lorsqu'aucun type est définie, vous recevez une erreur.

Exemple :

<StartTime>2017-7-16 12:00:00</StartTime>

Élément <Distributed>

Une installation Edge peut utiliser un ou plusieurs processeurs de message pour traiter les requêtes. Définissez cet élément sur true pour spécifier que la règle doit conserver un compteur central et le synchroniser en continu sur tous les processeurs de message. Les processeurs de messages peuvent se trouver dans plusieurs zones et/ou régions de disponibilité.

Si vous utilisez la valeur par défaut de false, vous pouvez dépasser votre quota, car le nombre de chaque processeur de message n'est pas partagé :

<Distributed>true</Distributed>

Pour garantir la synchronisation et la mise à jour des compteurs à chaque requête, définissez <Distributed> et <Synchronous> sur "true" :

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

Élément <Synchron>

Définissez la valeur sur true pour mettre à jour un compteur de quota distribué de manière synchrone. Cela signifie que la mise à jour du compteur est effectuée en même temps que le quota est vérifié pour une requête adressée à l'API. Définissez la valeur sur true s'il est essentiel de ne pas autoriser les appels d'API au-delà du quota.

Définissez la valeur sur false pour mettre à jour le compteur de quota de manière asynchrone. Cela signifie que certains appels d'API dépassant le quota peuvent passer, selon la fréquence de mise à jour asynchrone du compteur de quotas dans le dépôt central. Toutefois, vous ne serez pas affecté par les répercussions potentielles sur les performances associées aux mises à jour synchrones.

L'intervalle de mise à jour asynchrone par défaut est de 10 secondes. Utilisez l'élément AsynchronousConfiguration pour configurer ce comportement asynchrone.

<Synchronous>false</Synchronous>

Élément <AsynchronousConfiguration>

Configure l'intervalle de synchronisation entre les compteurs de quotas distribués lorsque l'élément de configuration de la règle <Synchronous> n'est pas présent, ou présent et défini sur false.

Vous pouvez effectuer la synchronisation après une période donnée ou un nombre de messages, à l'aide des éléments enfants SyncIntervalInSeconds ou SyncMessageCount. Ces éléments s'excluent mutuellement. Exemple :

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

ou

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Élément <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Utilisez cette option pour remplacer le comportement par défaut dans lequel les mises à jour asynchrones sont effectuées après un intervalle de 10 secondes.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

L'intervalle de synchronisation doit être supérieur à 10 secondes, comme décrit dans la section Limites.

Élément <AsynchronousConfiguration>/<SyncMessageCount>

Spécifie le nombre de requêtes sur tous les processeurs de messages Apigee entre les mises à jour de quotas.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Cet exemple indique que le nombre de quotas est mis à jour toutes les 5 requêtes sur chaque processeur de messages Apigee Edge.

Élément <Identifier>

Utilisez l'élément <Identifier> pour configurer la règle afin de créer des compteurs uniques basés sur une variable de flux.

Si vous n'utilisez pas cet élément, la règle utilise un seul compteur appliqué au quota.

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.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>

Attributs

Élément <MessageWeight>

Permet de spécifier la pondération attribuée à chaque message. Lapondération des messages vous permet d'augmenter l'impact des messages de requête qui, par exemple, consomment plus de ressources de calcul que d'autres.

Par exemple, vous souhaitez comptabiliser les messages POST deux fois plus "lourds" ou coûteux en tant que messages GET. Par conséquent, vous définissez MessageWeight sur 2 pour une requête POST et sur 1 pour une requête GET. Vous pouvez même définir MessageWeight sur 0 pour que la requête n'ait pas d'incidence sur le compteur. Dans cet exemple, si le quota est de 10 messages par minute et que le paramètre MessageWeight pour les requêtes POST est défini sur 2, le quota autorise cinq requêtes POST dans un intervalle de 10 minutes. Toute requête supplémentaire, POST ou GET, avant la réinitialisation du compteur est rejetée.

Une valeur représentant MessageWeight doit être spécifiée par une variable de flux et peut être extraite d'en-têtes HTTP, de paramètres de requête, d'une charge utile de requête XML ou JSON ou de toute autre variable de flux. Par exemple, définissez-la dans un en-tête nommé weight :

<MessageWeight ref="message_weight"/>

Variables de flux

Les variables de flux prédéfinies suivantes sont automatiquement renseignées lors de l'exécution d'une règle de quota. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie 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.

Erreurs de déploiement

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Exemple de règle de défaillance

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Schémas

Articles associés

Règle ResetQuota

SpikeArrest règlement

Comparer les règles de quota, SpikeArrest et de limitation du débit