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 :

Introduction (nouvelle version de Edge)

Introduction (Classic Edge)

Quotas dynamiques

Distribués et synchrones

Pondération des messages

Agenda

Période glissante

Flexi

Quotas conditionnels

Variables de flux

Traitement des erreurs

Exemples

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

Quotas plus dynamiques

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

Les quotas dynamiques vous permettent de configurer une seule règle de quota appliquant différents paramètres de quota en fonction des informations transmises à la règle de quota. Dans ce contexte, un autre terme applicable aux paramètres de quota est "forfait".  Les quotas dynamiques vérifient le "forfait" des applications, puis appliquent ces paramètres.

Remarque : Si vous spécifiez à la fois une valeur et une référence pour un élément, la référence obtient la priorité. Si la référence n'est pas renvoyée au moment de l'exécution, la valeur est utilisée.

Par exemple, lorsque vous créez un produit d'API, vous pouvez éventuellement définir la limite de quota, l'unité de temps et l'intervalle autorisés. Toutefois, définir ces valeurs sur le produit d'API n'impose pas leur utilisation dans un proxy d'API. Vous devez également ajouter une règle de quota au proxy d'API qui lit ces valeurs. Voir Créer des produits API pour plus d'informations.

Dans l'exemple ci-dessus, le proxy d'API contenant la règle de quota utilise une règle VerifyAPIKey, nommée verify-api-key, pour valider la clé API transmise dans une requête. La règle de quota accède ensuite aux variables de flux à partir de la règle VerifyAPIKey pour lire les valeurs de quota définies sur le produit d'API. Pour en savoir plus sur les variables de flux VerifyAPIKey, consultez la page Valider la règle de clé API.

Vous pouvez également définir des attributs personnalisés pour des développeurs ou applications spécifiques, puis lire ces valeurs dans la règle de quota. Par exemple, vous souhaitez définir différentes valeurs de quota pour chaque développeur. Dans ce cas, vous définissez des attributs personnalisés sur le développeur, qui contiennent la limite, l'unité de temps et l'intervalle. Vous référencez ensuite ces valeurs dans la règle de quota comme indiqué ci-dessous :

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

Cet exemple utilise également les variables de flux VerifyAPIKey pour référencer les attributs personnalisés définis sur le développeur.

Vous pouvez utiliser n'importe quelle variable pour définir les paramètres de la règle de quota. Ces variables peuvent provenir des éléments suivants :

  • Variables de flux
  • Propriétés du produit d'API, de l'application ou du développeur
  • Mappage clé-valeur (KVM)
  • Un en-tête, un paramètre de requête, un paramètre de formulaire, etc.

Pour chaque proxy d'API, vous pouvez ajouter une règle de quota faisant référence à la même variable que toutes les autres règles de quotas de tous les autres proxys. La règle de quota peut faire référence à des variables uniques pour cette règle et ce proxy.

Heure de début

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

Pour un quota dont la valeur type est définie sur calendar, vous devez définir une valeur <StartTime> explicite. La valeur horaire correspond à l'heure GMT, et non à l'heure locale. Si vous ne fournissez pas de valeur <StartTime> pour une stratégie de type calendar, Edge affiche une erreur.

Le compteur de quotas pour chaque application est actualisé en fonction des valeurs <StartTime>, <Interval> et <TimeUnit>. Dans cet exemple, le quota commence à être comptabilisé à 10h30 GMT le 18 février 2017 et s'actualise toutes les 5 heures. Par conséquent, la prochaine actualisation est fixée à 18:30 GMT le 18 février 2017.

Compteur d'accès

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

Un proxy d'API a accès aux variables de flux définies par la règle de quota. Vous pouvez accéder à ces variables de flux dans le proxy d'API pour effectuer un traitement conditionnel, surveiller la règle lorsqu'elle se rapproche de la limite de quota, renvoyer le compteur de quota actuel à une application, ou pour d'autres raisons.

Comme l'accès aux variables de flux de la règle est basé sur l'attribut name des règles, pour la règle ci-dessus nommée QuotaPolicy, vous accédez à ses variables de flux sous la forme suivante :

  • ratelimit.QuotaPolicy.allowed.count : nombre autorisé.
  • ratelimit.QuotaPolicy.used.count : valeur de compteur actuelle.
  • ratelimit.QuotaPolicy.expiry.time : heure UTC lorsque le compteur est réinitialisé.

Vous pouvez accéder à de nombreuses autres variables de flux, comme décrit ci-dessous.

Par exemple, vous pouvez utiliser la règle AssignMessage suivante pour renvoyer les valeurs des variables de flux de quota en tant qu'en-têtes de réponse :

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

Première requête

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

Utilisez cet exemple de code pour appliquer un quota de 10 000 appels par heure. La règle réinitialise le compteur de quota en haut de chaque heure. Si le compteur atteint le quota de 10 000 appels avant la fin de l'heure, les appels au-delà de 10 000 sont rejetés.

Par exemple, si le compteur commence à 2017-07-08 07:00:00, il est réinitialisé à 0 à 2017-07-08 08:00:00 (1 heure à partir de l'heure de début). Si le premier message est reçu à 2017-07-08 07:35:28 et que le nombre de messages atteint 10 000 avant 2017-07-08 08:00:00, les appels au-delà de ce nombre sont refusés jusqu'à ce que le décompte soit réinitialisé en haut de l'heure.

Le délai de réinitialisation du compteur est basé sur la combinaison des options <Interval> et <TimeUnit>. Par exemple, si vous définissez <Interval> sur 12 pour une <TimeUnit> en heures, le compteur est réinitialisé toutes les 12 heures. Vous pouvez définir le paramètre <TimeUnit> en minutes, heures, jours, semaines ou mois.

Vous pouvez référencer cette règle à plusieurs endroits de votre proxy d'API. Par exemple, vous pouvez la placer dans le PreFlow du proxy afin qu'il soit exécuté à chaque requête. Vous pouvez également la placer sur plusieurs flux dans le proxy d'API. Si vous utilisez cette règle à plusieurs endroits du proxy, elle conserve un compteur unique mis à jour par toutes les instances de la règle.

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

Définir un identifiant

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

Par défaut, une règle de quota définit un seul compteur pour le proxy d'API, quelle que soit l'origine d'une requête. Vous pouvez également utiliser l'attribut <Identifier> avec une règle de quota pour gérer des compteurs distincts en fonction de la valeur de l'attribut <Identifier>.

Par exemple, utilisez le tag <Identifier> pour définir des compteurs distincts pour chaque ID client. En cas de requête envoyée à votre proxy, l'application cliente transmet un en-tête contenant clientID, comme illustré dans l'exemple ci-dessus.

Vous pouvez spécifier n'importe quelle variable de flux pour l'attribut <Identifier>. Par exemple, vous pouvez spécifier qu'un paramètre de requête nommé id contient l'identifiant unique :

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

Si vous appliquez la règle VerifyAPIKey pour valider la clé API ou les règles OAuthV2 avec des jetons OAuth, vous pouvez utiliser les informations de la clé API ou du jeton pour définir des compteurs individuels pour la même règle de quota. Par exemple, le tag <Identifier> suivant utilise la variable de flux client_id d'une règle VerifyAPIKey nommée verify-api-key :

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

Chaque valeur client_id unique définit désormais son propre compteur dans la règle de quota.

Classe

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

Vous pouvez définir les limites de quota de manière dynamique en utilisant un nombre de quotas basé sur une classe. Dans cet exemple, la limite de quota est déterminée par la valeur de l'en-tête developer_segment transmise avec chaque requête. Cette variable peut avoir la valeur platinum ou silver. Si l'en-tête comporte une valeur non valide, la règle renvoie une erreur d'erreur de 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 :

Unité de temps Réinitialisation sur les valeurs par défaut (ou nulles) Réinitialisation de l'agenda Réinitialisation Flexi
minute Début de la minute suivante Une minute après <StartTime> Une minute après la première requête
heure Haut de l'heure suivante Une heure après <StartTime> Une heure après la première requête
jour À minuit GMT du jour actuel 24 heures après <StartTime> 24 heures après la première requête
semaine À minuit GMT le dimanche à la fin de la semaine Une semaine après <StartTime> Une semaine après la première requête
mois À minuit GMT le dernier jour du mois Un mois (28 jours) après <StartTime> Un mois (28 jours) après la première requête

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.

Attribut Description Par défaut Présence
type

Permet de déterminer quand et comment le compteur de quotas vérifie l'utilisation du quota. Pour plus d'informations, consultez la page Types de règles de quotas.

Si vous omettez de valeur type, le compteur commence au début. de la minute/heure/jour/semaine/mois.

Les valeurs valides sont les suivantes :

  • calendar : configure un quota basé sur une heure de début explicite. Le compteur de quota de chaque application est actualisé en fonction des valeurs <StartTime>, <Interval> et <TimeUnit> que vous avez définies.
  • rollingwindow : configurer un quota qui utilise une "fenêtre glissante" pour déterminer l'utilisation du quota. Avec rollingwindow, vous déterminez la taille de la fenêtre à l'aide des éléments <Interval> et <TimeUnit>. par exemple, 1 jour. Lorsqu'une requête arrive, Edge examine l'heure exacte de la requête (par exemple, 17h01), comptabilise le nombre de requêtes reçues entre 17h et 17h le lendemain (un jour), et détermine si le quota a été dépassé pendant cette période.
  • flexi : configure un quota qui déclenche le démarrage du compteur lorsque le premier message de requête est reçu d'une application, et est réinitialisé en fonction des valeurs <Interval>, et <TimeUnit>.
agenda Facultative

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

Attribut Description Par défaut Présence
name

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, en utilisant un nom différent, en langage naturel.

ND Valeur
continueOnError

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.

faux Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

vrai Facultatif
async

Cet attribut est obsolète.

faux Obsolète

É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>
Par défaut

ND

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Présence Facultatif
Type Chaîne

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

Valeur par défaut : ND
Présence : Facultatif
Type : Entier

Attributs

Attribut Description Par défaut Présence
nombre

Permet de spécifier le nombre de messages pour le quota.

Par exemple, une valeur d'attribut count de 100, Interval de 1, et une valeur TimeUnit en mois spécifie un quota de 100 messages par mois.

2000 Facultatif
countRef

Permet de spécifier une variable de flux contenant le nombre de messages d'un quota. countRef est prioritaire sur l'attribut count.

aucun Facultative

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

Valeur par défaut : ND
Présence : Facultatif
Type : ND

Attributs

Attribut Description Par défaut Présence
ref

Permet de spécifier une variable de flux contenant la classe de quota pour un quota.

aucun Valeur

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

Valeur par défaut : ND
Présence : Facultatif
Type : ND

Attributs

Attribut Description Par défaut Présence
classe

Définit le nom du compteur de quota.

aucun Obligatoire
nombre Spécifie la limite de quota pour le compteur. aucun Valeur

É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>
Valeur par défaut : aucun
Présence : Requis
Type : Entier

Attributs

Attribut Description Par défaut Présence
ref

Permet de spécifier une variable de flux contenant l'intervalle pour un quota. ref est prioritaire sur une valeur d'intervalle explicite. Si une référence et une valeur sont spécifiées, la valeur obtient la priorité. Si ref n'est pas renvoyé au moment de l'exécution, la valeur est utilisée.

aucun Facultative

É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>
Valeur par défaut : aucun
Présence : Requis
Type :

Chaîne. Sélectionnez minute, hour, day, week ou month.

Attributs

Attribut Description Par défaut Présence
ref Permet de spécifier une variable de flux contenant l'unité de temps d'un quota. ref a priorité sur une valeur d'intervalle explicite. Si l'opération ref n'est pas renvoyée au moment de l'exécution, la valeur est utilisée. aucun Facultative

É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>
Valeur par défaut : aucun
Présence : Obligatoire lorsque type est défini sur calendar.
Type :

Chaîne de date et heure, au format ISO 8601.

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

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

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>
Valeur par défaut : faux
Présence : Facultatif
Type : Boolean

É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>
Valeur par défaut : faux
Présence : Facultatif
Type : Boolean

É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>
Valeur par défaut : SyncIntervalInSeconds = 10 secondes
Présence : Facultatif ; ignoré lorsque <Synchronous> est défini sur true.
Type :

Éléments géographiques multifonctionnels

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

Valeur par défaut : 10
Présence : Facultatif
Type :

Entier

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

Valeur par défaut : n/a
Présence : Facultatif
Type :

Entier

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

Vous pouvez créer des compteurs uniques pour les caractéristiques définies par une variable de flux. Par exemple, vous pouvez utiliser l'adresse e-mail du développeur pour lier un quota à un développeur spécifique. Vous pouvez utiliser diverses variables pour identifier un quota, que vous utilisiez des variables personnalisées ou des variables prédéfinies, telles que celles disponibles avec la règle de clé API Verify. Consultez également la documentation de référence sur les variables.

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"/>
Valeur par défaut : ND
Présence : Facultatif
Type :

Chaîne

Attributs

Attribut Description Par défaut Présence
ref

Spécifie une variable de flux qui identifie le compteur à utiliser pour la requête. L'identifiant peut avoir un en-tête HTTP, un paramètre de requête, un paramètre de formulaire ou un contenu de message propre à chaque application, utilisateur d'application, développeur d'application, produit d'API ou autre caractéristique.

L'<Identifier> le plus souvent utilisé pour identifier les applications de manière unique, est client_id. client_id est un autre nom de la clé API, ou clé client, générée pour une application lorsqu'elle est enregistrée dans une organisation sur Apigee Edge. Vous pouvez utiliser cet identifiant si vous avez activé une clé API ou des règles d'autorisation OAuth pour votre API.

Dans certains cas, les paramètres de quota doivent être récupérés lorsqu'aucun client_id n'est disponible, par exemple lorsqu'aucune règle de sécurité n'est mise en place. Dans ces situations, vous pouvez utiliser la règle AccessEntity pour récupérer les paramètres de produit d'API appropriés, extraire les valeurs à l'aide de ExtractVariables, puis utiliser la variable de contexte extraite dans la règle de quota. Pour en savoir plus, consultez la section Règle AccessEntity.

ND Facultative

É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"/>
Valeur par défaut : ND
Présence : Facultatif
Type :

Entier

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.

Variables Type Autorisations Description
ratelimit.{policy_name}.allowed.count Long En lecture seule Renvoie le nombre de quotas autorisés
ratelimit.{policy_name}.used.count Long En lecture seule Renvoie le quota actuel utilisé dans un intervalle de quota
ratelimit.{policy_name}.available.count Long En lecture seule Renvoie le nombre de quotas disponibles dans l'intervalle de quota
ratelimit.{policy_name}.exceed.count Long En lecture seule Renvoie 1 une fois le quota dépassé
ratelimit.{policy_name}.total.exceed.count Long En lecture seule Renvoie 1 une fois le quota dépassé
ratelimit.{policy_name}.expiry.time Long En lecture seule

Renvoie le temps UTC en millisecondes qui détermine la date d'expiration du quota et le début d'un nouvel intervalle.

Lorsque le type de règle de quota est rollingwindow, cette valeur n'est pas valide, car l'intervalle de quota n'expire jamais.

ratelimit.{policy_name}.identifier Chaîne En lecture seule Renvoie la référence de l'identifiant (client) associée à la règle.
ratelimit.{policy_name}.class Chaîne En lecture seule Renvoie la classe associée à l'identifiant client
ratelimit.{policy_name}.class.allowed.count Long En lecture seule Renvoie le nombre de quotas autorisés défini dans la classe
ratelimit.{policy_name}.class.used.count Long En lecture seule Renvoie le quota utilisé dans une classe
ratelimit.{policy_name}.class.available.count Long En lecture seule Renvoie le nombre de quotas disponibles dans la classe
ratelimit.{policy_name}.class.exceed.count Long En lecture seule Renvoie le nombre de requêtes qui dépassent la limite définie dans la classe dans l'intervalle de quota actuel
ratelimit.{policy_name}.class.total.exceed.count Long En lecture seule Renvoie le nombre total de requêtes qui dépassent la limite définie pour la classe parmi tous les intervalles de quotas. Il correspond donc à la somme de class.exceed.count pour tous les intervalles de quota
ratelimit.{policy_name}.failed Booléen En lecture seule

Indique si la règle a échoué (vrai ou faux)

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.

Code d'erreur État HTTP Cause Corriger
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Cette erreur se produit si l'élément <Interval> n'est pas défini dans la règle de quota. Cet élément est obligatoire et permet de spécifier l'intervalle de temps applicable au quota. L'intervalle de temps peut être exprimé en minutes, en heures, en jours, en semaines ou en mois, comme défini dans l'élément <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Cette erreur se produit si l'élément <TimeUnit> n'est pas défini dans la règle de quota. Cet élément est obligatoire et permet de spécifier l'unité de temps applicable au quota. L'intervalle de temps peut être exprimé en minutes, en heures, en jours, en semaines ou en mois.
policies.ratelimit.InvalidMessageWeight 500 Cette erreur se produit si la valeur de l'élément <MessageWeight> spécifiée via une variable de flux n'est pas valide (valeur non entière).
policies.ratelimit.QuotaViolation 500 La limite de quota a été dépassée. ND

Erreurs de déploiement

Nom de l'erreur Cause Corriger
InvalidQuotaInterval Si l'intervalle de quota spécifié dans l'élément <Interval> n'est pas un entier, le déploiement du proxy d'API échoue. Par exemple, si l'intervalle de quota spécifié est de 0,1 dans l'élément <Interval>, le déploiement du proxy d'API échoue.
InvalidQuotaTimeUnit Si l'unité de temps spécifiée dans l'élément <TimeUnit> n'est pas acceptée, le déploiement du proxy d'API échoue. Les unités de temps acceptées sont minute, hour, day, week et month.
InvalidQuotaType Si le type de quota spécifié par l'attribut type dans l'élément <Quota> n'est pas valide, le déploiement du proxy d'API échoue. Les types de quotas acceptés sont default, calendar, flexi et rollingwindow.
InvalidStartTime Si le format de l'heure spécifiée dans l'élément <StartTime> n'est pas valide, le déploiement du proxy d'API échoue. Le format valide est yyyy-MM-dd HH:mm:ss. Il correspond au format de date et d'heure ISO 8601. Par exemple, si l'heure spécifiée dans l'élément <StartTime> est 7-16-2017 12:00:00, le déploiement du proxy d'API échoue.
StartTimeNotSupported Si l'élément <StartTime> est spécifié et que le type de quota n'est pas calendar, le déploiement du proxy d'API échoue. L'élément <StartTime> n'est disponible que pour le type de quota calendar. Par exemple, si l'attribut type est défini sur flexi ou rolling window dans l'élément <Quota>, le déploiement du proxy d'API échoue.
InvalidTimeUnitForDistributedQuota Si l'élément <Distributed> est défini sur true et que l'élément <TimeUnit> est défini sur second, le déploiement du proxy d'API échoue. L'unité de temps second n'est pas valide pour un quota distribué.
InvalidSynchronizeIntervalForAsyncConfiguration Si la valeur spécifiée pour l'élément <SyncIntervalInSeconds> au sein de l'élément <AsynchronousConfiguration> d'une règle de quota est inférieure à zéro, le déploiement du proxy d'API échoue.
InvalidAsynchronizeConfigurationForSynchronousQuota Si la valeur de l'élément <AsynchronousConfiguration> est définie sur true dans une règle de quota, qui possède également une configuration asynchrone définie à l'aide de l'élément <AsynchronousConfiguration>, le déploiement du proxy d'API échoue.

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.

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 "QuotaViolation"
ratelimit.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. ratelimit.QT-QuotaPolicy.failed = true

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>
<ph type="x-smartling-placeholder">

Schémas

Articles associés

Règle ResetQuota

SpikeArrest règlement

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