Règles de quotas

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

Présentation

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 de quotas gère les compteurs qui calculent 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.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

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

Une variation de la règle de quotas, appelée règle 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.

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 d'applications
  • De nombreux autres critères

N'utilisez pas la règle de quotas pour vous protéger contre les pics de trafic globaux. Utilisez pour cela la règle SpikeArrest.

Vidéos

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

Introduction

Quotas dynamiques

Distribués et synchrones

Pondération des messages

Agenda

Période glissante

Flexi

Quotas conditionnels

Variables de flux

Gestion des exceptions

Types de règles de quotas

La règle de quotas accepte plusieurs modes de démarrage et de réinitialisation du compteur de quota. Vous pouvez définir lequel utiliser avec l'attribut type sur l'élément <Quota>, comme le montre l'exemple suivant :

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

Les valeurs valides pour type 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 : configure 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, Apigee examine l'heure exacte de la requête (par exemple, 17h01), comptabilise le nombre de requêtes reçues entre 17h01 et 17h01 le jour précédent (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>.

Le tableau suivant décrit les réinitialisations de quota pour chaque type :

Unité de temps Type
default (ou nul) calendar 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

Lorsqu'une règle de quota s'exécute dans un flux de proxy d'API, le compteur de quota diminue. Lorsque le compteur atteint sa limite, aucun autre appel d'API associé à ce compteur n'est autorisé. En fonction de votre configuration, la règle de quota peut utiliser un ou plusieurs compteurs. Il est important de comprendre quand plusieurs compteurs sont utilisés et comment ils se comportent.

Comptage des quotas pour les produits API

Si votre proxy d'API est inclus dans un produit d'API, vous pouvez configurer la règle de quota pour utiliser les règles de quota définies dans ce produit. Un produit d'API peut spécifier des règles de quota au niveau du produit ou au niveau des opérations individuelles.

Un compteur de quota distinct est géré pour chaque opération définie dans un produit d'API, et les règles suivantes sont observées :

  • Si un quota est défini pour une opération, les règles de l'opération ont priorité sur les règles de quota définies au niveau du produit. Un compteur de quota distinct est créé pour chaque opération. Tous les appels d'API vers le chemin d'accès d'une opération incrémentent son compteur.
  • Si aucun quota n'est défini pour une opération, la règle de quota au niveau du produit est appliquée. Cependant, un compteur de quota distinct est toujours géré pour l'opération. Il est important de comprendre que dans ce cas, même si la règle de quota provient de la définition au niveau du produit, l'opération conserve son propre compteur.
  • Si le produit d'API n'inclut aucune définition de quota, que ce soit au niveau du produit ou de l'opération, les règles de quota spécifiées dans les règles s'appliquent. Dans ce cas également, un compteur de quota distinct est utilisé pour chaque opération du produit d'API.

Les sections suivantes décrivent plus en détail les options et le comportement du compteur.

Configurer des compteurs au niveau du proxy d'API

Il est possible de configurer un produit d'API pour gérer un compteur de quota au niveau du proxy d'API. Dans ce cas, la configuration de quota spécifiée au niveau du produit d'API est partagée par toutes les opérations qui ne disposent pas de leur propre quota. Cette configuration revient à créer un compteur global au niveau du proxy d'API pour ce produit d'API.

Pour atteindre cette configuration, vous devez utiliser l'API Apigee /apiproducts pour créer ou mettre à jour le produit, puis définir l'attribut quotaCountScope sur PROXY dans la requête de création ou de mise à jour. Avec la configuration PROXY, toutes les opérations définies pour le produit d'API et associées au même proxy qui n'ont pas leur propre compteur partageront le même compteur de quota défini au niveau du produit d'API.

Dans la figure 1, les opérations 1 et 2 sont associées à Proxy1, et les opérations 4 et 5 sont associées à Proxy3. Étant donné que quotaCounterScope=PROXY est défini dans le produit d'API, chacune de ces opérations partage le paramètre de quota au niveau du produit d'API. Bien que ces opérations partagent la même configuration de quota, elles utilisent des compteurs distincts, en fonction de leur association de proxy. En revanche, l'opération 3 possède son propre ensemble de configurations de quota et n'est donc pas affectée par l'option quotaCounterScope.

Figure 1 : Utilisation de l'option quotaCounterScope

Par défaut, si aucun quota n'est défini pour une opération, la règle de quota au niveau du produit est appliquée. Cependant, un compteur de quota distinct est toujours géré pour l'opération.

Comptage des quotas si aucun produit d'API n'est utilisé

Si aucun produit d'API n'est associé à un proxy d'API, une règle de quota ne gère qu'un seul compteur, quel que soit le nombre de références à ce compteur 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 quotas à plusieurs endroits d'un flux de proxy d'API, qui peut entraîner une consommation de quota plus rapide que prévu, est un anti-modèle décrit dans l'article Présentation des antimodèles.

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.

Créer plusieurs compteurs via une configuration de règle

Vous pouvez 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, 2021-02-04 correspond au 4 février 2021.

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, 2021-02-04 24:00:00 est la même date et la même heure que 2021-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 Gérer les produits API.

Configurer des compteurs de quotas partagés

En règle générale, la règle de quotas comptabilise toutes les requêtes envoyées à un proxy d'API. Dans certains cas, vous pouvez avoir besoin d'appliquer le compteur de quotas de requêtes entrantes, mais également d'incrémenter le compteur de quota pour les réponses cibles qui répondent à une condition spécifiée. Trois éléments de règle de quota utilisés conjointement, <SharedName>, <CountOnly> et <EnforceOnly>, vous permettent de personnaliser la règle de quota pour appliquer le quota de requêtes entrantes et comptabiliser les réponses cibles en fonction d'une condition que vous spécifiez.

Par exemple, supposons que vous souhaitiez incrémenter le compteur de quotas d'un proxy d'API où les réponses de la cible de backend ont un code d'état HTTP 200. Pour réaliser ce comptage spécialisé, procédez comme suit :

  • Ajoutez une règle de quota au flux de requête ProxyEndpoint avec l'élément <SharedName> défini avec une valeur de nom et l'élément <EnforceOnly> défini sur true.
  • Ajoutez une autre règle de quota au flux de réponse ProxyEndpoint avec l'élément <SharedName> défini sur la même valeur de nom que la première règle, et l'élément <CountOnly> défini sur true.
  • Placez la deuxième règle de quota (celle avec <CountOnly>) dans une étape conditionnelle qui précise la condition entraînant une incrémentation du compteur de quota.

Pour obtenir un exemple illustrant l'utilisation de compteurs partagés, consultez Compteurs partagés dans la section Exemples.

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 quotas appliquant différents paramètres de quota en fonction des informations transmises à la règle de quotas. 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.

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

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, pour définir différentes valeurs de quota par développeur. vous définissez des attributs personnalisés pour le développeur contenant 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)
  • En-tête, paramètre de requête, 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>2021-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 règle de type calendar, Apigee affiche une erreur.

Le compteur de quota 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 2021 et s'actualise toutes les 5 heures. Par conséquent, la prochaine actualisation est fixée à 15:30 GMT le 18 février 2021.

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

Compteurs partagés

L'exemple suivant montre comment configurer un compteur partagé pour un proxy d'API, où le compteur de quota est également incrémenté lorsque la réponse cible correspond à l'état HTTP 200. Étant donné que les deux règles de quota utilisent la même valeur <SharedName>, elles partagent le même compteur de quota. Pour en savoir plus, consultez la page Configurer des compteurs de quotas partagés.

Exemple de configuration de ProxyEndpoint : 

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

Premier exemple de règle de quota :

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

Deuxième exemple de règle de quota :

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

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 à 2021-07-08 07:00:00, il est réinitialisé à 0 à 2021-07-08 08:00:00 (1 heure à partir de l'heure de début). Si le premier message est reçu à 2021-07-08 07:35:28 et que le nombre de messages atteint 10 000 avant 2021-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>2021-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 quotas 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 quotas. Par exemple, l'élément <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.

Élément <Quota>

Voici les attributs et les éléments enfants de <Quota>. 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.my-verify-key-policy.apiproduct.* ci-dessous sont disponibles par défaut lorsqu'une règle VerifyAPIKey appelée my-verify-key-policy 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 continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

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

Attribut Description Par défaut Presence
type

Définit le type de règle de quotas, qui détermine quand et comment le compteur de quota vérifie l'utilisation du quota, ainsi que le processus de réinitialisation.

Si vous ne définissez pas type, le compteur démarre au début de la minute/heure/jour/semaine/mois.

Les valeurs valides sont les suivantes :

  • calendar
  • rollingwindow
  • flexi

Pour obtenir une description complète de chaque type, consultez la section Types de règles de quotas.

 N/A Facultatif

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

Attribut Description Par défaut Presence
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.

 N/A Obligatoire
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. Voir également :

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

 true Facultatif
async

Cet attribut est obsolète.

 false 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

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence Facultatif
Type Chaîne

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

Peut également contenir un élément <Class> qui conditionne l'élément <Allow> en fonction d'une variable de flux.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type entier ou complexe
Élément parent <Quota>
Éléments enfants <Class>

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.

Vous pouvez également spécifier un élément <Class> en tant qu'enfant de <Allow> pour déterminer le décompte autorisé de la règle en fonction d'une variable de flux. Apigee met en correspondance la valeur de la variable de flux avec l'attribut class de l'élément <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>

Le tableau suivant répertorie les attributs de <Allow> :

Attribut Description Par défaut Presence
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 Facultatif

<Class>

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.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Allow>
Éléments enfants <Allow> (enfant de <Class>)

Pour utiliser l'élément <Class>, spécifiez une variable de flux avec l'attribut ref de l'élément <Class>. Apigee utilise ensuite la valeur de la variable de flux pour sélectionner l'un des éléments enfants <Allow> afin de déterminer le décomtpe autorisé de la règle. Apigee met en correspondance la valeur de la variable de flux avec l'attribut class de l'élément <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.

Le tableau suivant répertorie les attributs de <Class> :

Attribut Description Par défaut Presence
ref Permet de spécifier une variable de flux contenant la classe de quota pour un quota. aucun Obligatoire

<Allow> (enfant de <Class>)

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.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Class>
Éléments enfants Aucune

Exemple :

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

Dans cet exemple, la règle de quota gère deux compteurs de quota nommés peak_time et off_peak_time. Celui qui est utilisé dépend du paramètre de requête transmis, comme illustré dans l'exemple <Class>.

Le tableau suivant répertorie les attributs de <Allow> :

Attribut Description Par défaut Presence
classe Définit le nom du compteur de quota. aucun Obligatoire
nombre Spécifie la limite de quota pour le compteur. aucun Obligatoire

<Interval>

Indique le nombre de périodes de calcul des quotas.

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

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

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

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

Le tableau suivant répertorie les attributs de <Interval> :

Attribut Description Par défaut Presence
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 Facultatif

<TimeUnit>

Spécifie l'unité de temps applicable au quota.

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

Sélectionnez minute, hour, day, week, month ou year.

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 : Obligatoire
Type : Chaîne

Le tableau suivant répertorie les attributs de <TimeUnit> :

Attribut Description Par défaut Presence
ref Spécifie une variable de flux contenant l'unité de temps d'un quota. ref a priorité sur une valeur d'intervalle explicite. Si ref n'est pas renvoyé au moment de l'exécution, la valeur d'intervalle est utilisée. aucun Facultatif

<StartTime>

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

Valeur par défaut N/A
Obligatoire ? Facultatif (obligatoire lorsque type est défini sur calendar)
Type Chaîne de date et heure, au format ISO 8601
Élément parent <Quota>
Éléments enfants Aucune

Vous devez fournir une valeur <StartTime> explicite lorsque type est 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'aucune valeur type n'est définie, Apigee renvoie une erreur.

Exemple :

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

<Distributed>

Détermine si Apigee utilise un ou plusieurs nœuds pour traiter les requêtes.

Valeur par défaut false
Obligatoire ? Facultatif
Type Booléen
Élément parent <Quota>
Éléments enfants Aucune

Définissez la valeur sur true pour spécifier que la règle doit conserver un compteur central et le synchroniser en continu sur tous les nœuds. Les nœuds peuvent se trouver dans plusieurs zones et/ou régions de disponibilité.

Si vous utilisez la valeur par défaut false, vous risquez de dépasser votre quota, car le décompte de chaque nœud n'est pas partagé :

<Distributed>false</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>

<Synchronous>

Détermine si un compteur de quota distribué doit être mis à jour de manière synchrone.

Valeur par défaut false
Obligatoire ? Facultatif
Type Booléen
Élément parent <Quota>
Éléments enfants Aucune

Définissez la valeur sur true pour mettre à jour un compteur de quota distribué de manière synchrone. Cela signifie que les mises à jour des compteurs sont effectuées 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 répertoire 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>

<AsynchronousConfiguration>

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

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Quota>
Éléments enfants <SyncIntervalInSeconds>
<SyncMessageCount>

Vous pouvez spécifier le comportement de synchronisation à l'aide des éléments enfants <SyncIntervalInSeconds> ou <SyncMessageCount>. Utilisez l'un ou l'autre de ces éléments. Exemple :

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

ou

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Lorsque seul <SyncIntervalInSeconds> est présent, le quota se synchronise toutes les N secondes, où N est la valeur spécifiée dans l'élément, quel que soit le nombre de messages traités.
  • Lorsque seul <SyncMessageCount> est présent, le quota se synchronise tous les M messages, où M est la valeur spécifiée dans l'élément, ou toutes les 10 secondes, selon la première occurrence.
  • Lorsque les deux éléments sont présents, le quota se synchronise tous les M messages ou toutes les N secondes, selon la première occurrence.
  • Lorsque <AsynchronousConfiguration> n'est pas présent ou qu'aucun élément enfant n'est présent, le quota se synchronise toutes les 10 secondes, quel que soit le nombre de messages traités.

<SyncIntervalInSeconds>

Remplace le comportement par défaut selon lequel les mises à jour asynchrones sont effectuées à un intervalle de 10 secondes.

Valeur par défaut 10 secondes
Obligatoire ? Facultatif
Type Entier
Élément parent <AsynchronousConfiguration>
Éléments enfants Aucune
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

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

<SyncMessageCount>

Indique le nombre de requêtes à traiter avant de synchroniser le compteur de quota.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Entier
Élément parent <AsynchronousConfiguration>
Éléments enfants Aucune
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Avec la configuration de cet exemple, sur chaque nœud, le décompte du quota se synchronise toutes les cinq requêtes ou toutes les 10 secondes, selon la première occurrence.

<Identifier>

Configure la règle pour créer des compteurs uniques en fonction d'une variable de flux.

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

Via l'élément identificateur, vous pouvez attribuer des décomptes d'appels à des buckets distincts définis par la valeur d'une variable de flux. Par exemple, vous pouvez utiliser la variable developer.id, qui est renseignée après une règle VerifyAPIKey, pour appliquer une limite de quota à toutes les instances de toutes les applications créées par chaque développeur spécifique. Vous pouvez également utiliser le client_id pour appliquer une limite de quota à chaque application. La configuration de la dernière option ressemble à ceci :

<Identifier ref="client_id"/>

Vous pouvez faire référence à une variable personnalisée que vous pouvez définir dans la règle AssignMessage ou la règle JavaScript, ou une variable définie implicitement, comme les variables définies par la règle VerifyAPIKey ou la règle VerifyJWT. Pour en savoir plus sur les variables, consultez la section Utiliser des variables de flux. Pour obtenir la liste des variables connues définies par Apigee, consultez la documentation de référence sur les variables.

Si vous n'utilisez pas cet élément, la règle attribue tous les décomptes d'appels à un seul compteur pour la règle de quota spécifique.

Cet élément est également abordé dans la section Comment fonctionne la règle de quotas si aucun identifiant n'est spécifié ?

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

Attribut Description Par défaut Presence
ref

Spécifie une variable de flux qui identifie le compteur à utiliser pour la requête. La variable peut faire référence à un en-tête HTTP, à un paramètre de requête, un paramètre de formulaire ou un élément du contenu du message, ou à une autre valeur permettant d'identifier la manière d'attribuer les décomptes d'appels.

client_id est couramment utilisé comme variable. client_id est également appelé clé API ou clé client, et est généré pour une application lorsqu'elle est enregistrée dans une organisation sur Apigee. Vous pouvez utiliser cet identifiant si vous avez activé une clé API ou des règles d'autorisation OAuth pour votre API.

 N/A Facultatif

<MessageWeight>

Indique le coût attribué à chaque message à des fins de quota. Utilisez cet élément pour augmenter l'impact des messages de requête qui, par exemple, consomment plus de ressources de calcul que d'autres.

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

Par exemple, vous souhaitez comptabiliser les messages POST deux fois plus 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"/>

<UseQuotaConfigInAPIProduct>

Définit les paramètres de quota pour un produit d'API, tels que les unités de temps, l'intervalle et le maximum autorisé.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Quota>
Éléments enfants <DefaultConfig>

Si vous ajoutez l'élément <UseQuotaConfigInAPIProduct> à la règle de quotas, Apigee ignore les éléments enfants <Allow>, <Interval> et <TimeUnit> de <Quota>.

L'élément <UseQuotaConfigInAPIProduct> est simplement un conteneur pour les paramètres par défaut que vous définissez à l'aide de l'élément <DefaultConfig>, comme le montre l'exemple suivant :

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Vous pouvez utiliser l'attribut stepName pour faire référence à une règle VerifyAPIKey ou à une opération de règle ValidateToken de la règle OAuthv2 dans le flux.

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

Attribut Description Par défaut Presence
stepName Identifie le nom de la règle d'authentification dans le flux. La cible peut être une règle VerifyAPIKey ou une règle OAuthv2. N/A Obligatoire

Pour en savoir plus, consultez les ressources suivantes :

<DefaultConfig>

Contient les valeurs par défaut pour le quota d'un produit d'API. Lorsque vous définissez <DefaultConfig>, les trois éléments enfants sont requis.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <UseQuotaConfigInAPIProduct>
Éléments enfants <Allow>
<Interval>
<TimeUnit>

Il est possible de définir ces valeurs sur l'opération du produit d'API (à l'aide de l'interface utilisateur ou de l'API des produits d'API) et dans la règle de quotas. Toutefois, si vous le faites, les paramètres du produit d'API ont la priorité et les paramètres de la règle de quotas sont ignorés.

La syntaxe de cet élément est la suivante :

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

L'exemple suivant spécifie un quota de 10 000 par semaine :

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Pour en savoir plus, consultez les ressources suivantes :

<SharedName>

Identifie cette règle de quota comme étant partagée. Toutes les règles de quota d'un proxy d'API ayant la même valeur <SharedName> partagent le même compteur de quota sous-jacent. Si cet élément est présent, les éléments <EnforceOnly> ou <CountOnly> doivent également être présents.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

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

<CountOnly>

Placez une règle de quota avec cet élément défini sur true dans une étape conditionnelle du flux de réponse ProxyEndpoint pour incrémenter le compteur de quota sous-jacent de manière conditionnelle. Si cet élément est présent, les éléments <SharedName> et <EnforceOnly> doivent également être présents.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

Valeur par défaut false
Obligatoire ? Facultatif
Type Booléen
Élément parent <Quota>
Éléments enfants Aucune

<EnforceOnly>

Placez une règle de quota avec cet élément défini sur true dans le flux de requête d'un proxy d'API. Cette configuration permet de partager les décomptes de quotas pour toute règle de quota du proxy d'API avec la même valeur <SharedName>. Si cet élément est présent, les éléments <SharedName> et <CountOnly> doivent également être présents.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

Valeur par défaut false
Obligatoire ? Facultatif
Type Booléen
Élément parent <Quota>
Éléments enfants Aucune

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, consultez la documentation de référence sur les variables de flux.

Variables Type Autorisations Description
ratelimit.{policy_name}.allowed.count Long En lecture seule Renvoie le décompte de quota autorisé.
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 décompte de quota disponible 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 quotas 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 renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

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

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 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 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. N/A

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 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 Quota, dont la configuration asynchrone est 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 Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "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>

Schémas

Articles associés

Règle ResetQuota

Règle SpikeArrest

Comparer les règles relatives aux quotas et aux pics d'Arrest