Criteri per le quote

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

icona norme

Panoramica

Una quota è un'allocazione di messaggi di richiesta che un proxy API può gestire in un periodo di tempo, ad esempio minuto, ora, giorno, settimana o mese. Il criterio per le quote gestisce i contatori che calcolano il numero di richieste ricevute dal proxy API. Questa funzionalità consente ai provider di API di applicare limiti al numero di chiamate API effettuate dalle app in un intervallo di tempo. Con i criteri per le quote puoi, ad esempio, limitare le app a 1 richiesta al minuto o a 10.000 richieste al mese.

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta la pagina Tipi di criteri.

Ad esempio, se una quota è definita come 10.000 messaggi al mese, la limitazione di frequenza inizia dopo il 10.000° messaggio. Non è importante se sono stati conteggiati 10.000 messaggi il primo o l'ultimo giorno di quel periodo; non sono consentite richieste aggiuntive fino a quando il contatore della quota non viene reimpostato automaticamente al termine dell'intervallo di tempo specificato o finché la quota non viene reimpostata esplicitamente tramite il criterio ResetQuota.

Una variante del criterio per le quote, il criterio SpikeArrest, impedisce picchi di traffico (o burst) che possono essere causati da un aumento improvviso dell'utilizzo, client con bug o attacchi dannosi.

Utilizza il criterio per le quote per configurare il numero di messaggi di richiesta consentiti da un proxy API in un periodo di tempo, ad esempio minuto, ora, giorno, settimana o mese. Puoi impostare la quota in modo che sia la stessa per tutte le app che accedono al proxy API oppure puoi impostare la quota in base a:

  • Il prodotto che contiene il proxy API
  • L'app che richiede l'API
  • Lo sviluppatore dell'app
  • Molti altri criteri

Non utilizzare il criterio per le quote per proteggerti dai picchi di traffico complessivi. In questo caso, utilizza il criterio SpikeArrest.

Video

Questi video introducono la gestione delle quote con i criteri per le quote:

Introduzione

Quota dinamica

Distribuito e sincrono

Peso del messaggio

Calendar

Finestre scorrevoli

Flex

Quota condizionale

Variabili di flusso

Gestione degli errori

Tipi di criteri per le quote

Il criterio per le quote supporta diversi modi per avviare e reimpostare il contatore della quota. Puoi definire quale utilizzare con l'attributo type nell'elemento <Quota>, come illustrato nell'esempio seguente:

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

I valori validi di type includono:

  • calendar: configura una quota in base a un'ora di inizio esplicita. Il contatore delle quote per ogni app viene aggiornato in base ai valori <StartTime>, <Interval> e <TimeUnit> che hai impostato.
  • rollingwindow: configura una quota che utilizza una "finestra temporale" per determinare l'utilizzo della quota. Con rollingwindow, determini la dimensione della finestra con gli elementi <Interval> e <TimeUnit>, ad esempio 1 giorno. Quando arriva una richiesta, Apigee esamina l'ora esatta della richiesta (ad esempio le 17:01), conteggia il numero di richieste ricevute tra quella data e le 17:01 del giorno precedente (1 giorno) e determina se la quota è stata superata o meno durante quella finestra.
  • flexi: configura una quota che fa sì che il contatore inizi quando viene ricevuto il primo messaggio di richiesta da un'app e che venga reimpostata in base ai valori <Interval> e <TimeUnit>.

La tabella seguente descrive le reimpostazioni della quota per ciascun tipo:

Unità di tempo Tipo
default (o nullo) calendar flexi
minuto Inizio del prossimo minuto Un minuto dopo <StartTime> Un minuto dopo la prima richiesta
ora Inizio della prossima ora Un'ora dopo <StartTime> Un'ora dopo la prima richiesta
giorno Mezzanotte GMT del giorno corrente 24 ore dopo <StartTime> 24 ore dopo la prima richiesta
settimana Mezzanotte GMT Domenica alla fine della settimana Una settimana dopo <StartTime> Una settimana dopo la prima richiesta
mese Mezzanotte GMT dell'ultimo giorno del mese Un mese (28 giorni) dopo <StartTime> Un mese (28 giorni) dopo la prima richiesta

Per type="calendar", devi specificare il valore di <StartTime>.

La tabella non elenca il valore per il tipo rollingwindow. Le quote di finestre continuative funzionano impostando la dimensione di una finestra di quota, ad esempio una finestra di un'ora o di un giorno. Quando arriva una nuova richiesta, il criterio determina se la quota è stata superata nell'ultimo periodo di tempo.

Ad esempio, definisci una finestra di due ore che consente 1000 richieste. Una nuova richiesta arriva alle 16:45.Il criterio calcola il conteggio della quota per la finestra delle ultime due ore, ovvero il numero di richieste a partire dalle 14:45. Se il limite di quota non è stato superato nell'intervallo di due ore, la richiesta è consentita.

Un minuto dopo, alle 16:46, è in arrivo un'altra richiesta. Ora il criterio calcola il conteggio delle quote a partire dalle 14:46 per determinare se il limite è stato superato.

Per il tipo rollingwindow, il contatore non viene mai reimpostato, ma viene ricalcolato a ogni richiesta.

Informazioni sui contatori delle quote

Quando un criterio per le quote viene eseguito in un flusso proxy API, il contatore delle quote viene ridotto. Quando il contatore raggiunge il limite, non sono consentite ulteriori chiamate API associate a quel contatore. A seconda della configurazione, il criterio per le quote potrebbe utilizzare uno o più contatori. È importante capire quando vengono utilizzati più contatori e il loro comportamento.

Come vengono conteggiate le quote per i prodotti API

Se il proxy API è incluso in un prodotto API, puoi configurare i criteri per le quote in modo che utilizzino le regole per le quote definite in quel prodotto. Un prodotto API può specificare regole di quota a livello di prodotto o a livello di singole operations.

Viene mantenuto un contatore delle quote separato per ogni operazione definita in un prodotto API e vengono osservate le seguenti regole:

  • Se per un'operazione è stata definita una quota, le relative regole hanno la precedenza sulle regole di quota definite a livello di prodotto. Viene creato un contatore della quota separato per ogni operazione. Qualsiasi chiamata API al percorso di un'operazione incrementa il contatore.
  • Se per un'operazione non è stata definita una quota, viene applicata la regola per la quota a livello di prodotto; tuttavia, viene comunque mantenuto un contatore separato per l'operazione. In questo caso, è importante comprendere che anche se la regola per la quota viene presa dalla definizione a livello di prodotto, l'operazione mantiene comunque il proprio contatore.
  • Se il prodotto API non include definizioni di quota, né a livello di prodotto né di operazione, vengono applicate regole di quota specificate nelle norme. Tuttavia, anche in questo caso viene mantenuto un contatore delle quote separato per ogni operazione nel prodotto API.

Le seguenti sezioni descrivono in maggiore dettaglio le opzioni e il comportamento dei contatori.

Configurazione dei contatori a livello di proxy API

È possibile configurare un prodotto API per mantenere un conteggio delle quote nell'ambito del proxy API. In questo caso, la configurazione della quota specificata a livello di prodotto API viene condivisa da tutte le operazioni per le quali non è specificata una quota propria. L'effetto di questa configurazione è creare un contatore globale a livello di proxy API per questo prodotto API.

Per ottenere questa configurazione, devi utilizzare l'API Apigee/apiproducts per creare o aggiornare il prodotto e impostare l' attributo quotaCountScope su PROXY nella richiesta di creazione o aggiornamento. Con la configurazione PROXY, tutte le operazioni definite per il prodotto API che sono associate allo stesso proxy e non dispongono di un proprio contatore condivideranno lo stesso contatore di quota impostato a livello di prodotto API.

Nella Figura 1, l'operazione 1 e 2 sono associate a Proxy1, mentre l'operazione 4 e 5 sono associate a Proxy3. Poiché quotaCounterScope=PROXY è configurato nel prodotto API, ciascuna di queste operazioni condivide l'impostazione della quota a livello di prodotto API. Tieni presente che, anche se queste operazioni condividono la stessa configurazione di quota, utilizzano contatori separati in base alla loro associazione proxy. D'altra parte, l'operazione 3 ha una propria configurazione della quota impostata, pertanto non è interessata dal flag quotaCounterScope.

Figura 1: utilizzo del flag quotaCounterScope

Per impostazione predefinita, se un'operazione non ha una quota definita, viene applicata la regola per la quota a livello di prodotto. Tuttavia, per l'operazione viene comunque mantenuto un contatore delle quote separato.

Come vengono conteggiate le quote se non è in uso nessun prodotto API

Se non esistono prodotti API associati a un proxy API, un criterio per le quote gestisce un unico contatore, indipendentemente dal numero di volte che lo fai riferimento in un proxy API. Il nome del contatore della quota si basa sull'attributo name del criterio.

Ad esempio, crei un criterio per le quote denominato MyQuotaPolicy con un limite di 5 richieste e lo collochi in più flussi (flusso A, B e C) nel proxy API. Anche se viene utilizzato in più flussi, mantiene un unico contatore aggiornato da tutte le istanze del criterio:

  • Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore = 1
  • Viene eseguito il flusso B -> MyQuotaPolicy viene eseguito e il relativo contatore = 2
  • Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore = 3
  • Viene eseguito il flusso C -> MyQuotaPolicy viene eseguito e il relativo contatore = 4
  • Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore = 5

La richiesta successiva a uno dei tre flussi viene rifiutata perché il contatore della quota ha raggiunto il proprio limite.

L'utilizzo dello stesso criterio per le quote in più di una posizione in un flusso di proxy API, che può causare involontariamente l'esaurimento della quota più velocemente del previsto, è un anti-pattern descritto in Introduzione agli antipattern.

In alternativa, puoi definire più criteri per le quote nel proxy API e utilizzare criteri diversi in ogni flusso. Ogni criterio per le quote gestisce il proprio contatore, basato sull'attributo name del criterio.

Creazione di più contatori tramite la configurazione dei criteri

Puoi utilizzare gli elementi <Class> o <Identifier> nel criterio per le quote per definire più contatori univoci in un singolo criterio. Se utilizzi questi elementi, un singolo criterio può mantenere diversi contatori in base all'app che effettua la richiesta, allo sviluppatore dell'app che esegue la richiesta, a un ID client o a un altro identificatore client e altro ancora. Consulta gli esempi precedenti per maggiori informazioni sull'utilizzo degli elementi <Class> o <Identifier>.

Notazione dell'ora

Tutti gli orari della quota sono impostati sul fuso orario UTC (Coordinated Universal Time).

La notazione dell'ora delle quote segue la notazione della data standard internazionale definita nello standard internazionale ISO 8601.

Le date sono definite anno, mese e giorno nel seguente formato: YYYY-MM-DD. Ad esempio, 2021-02-04 rappresenta il 4 febbraio 2021.

L'ora del giorno è definita in ore, minuti e secondi nel seguente formato: hours:minutes:seconds. Ad esempio, 23:59:59 rappresenta l'ora un secondo prima della mezzanotte.

Tieni presente che sono disponibili due notazioni, 00:00:00 e 24:00:00, per distinguere le due notti che possono essere associate a una data. Di conseguenza, 2021-02-04 24:00:00 corrisponde alla stessa data e ora di 2021-02-05 00:00:00. Quest'ultima è in genere la notazione preferita.

Recupero delle impostazioni della quota dalla configurazione del prodotto API

Puoi impostare limiti di quota nelle configurazioni dei prodotti API. Questi limiti non applicano automaticamente la quota. Puoi però fare riferimento alle impostazioni delle quote dei prodotti in un criterio per le quote. Ecco alcuni vantaggi dell'impostazione di una quota sul prodotto a cui fare riferimento per i criteri di quota:

  • I criteri per le quote possono utilizzare un'impostazione uniforme su tutti i proxy API nel prodotto API.
  • Puoi apportare modifiche in fase di runtime all'impostazione della quota in un prodotto API. I criteri per le quote che fanno riferimento a questo valore vengono aggiornati automaticamente.

Per ulteriori informazioni sull'utilizzo delle impostazioni di quota da un prodotto API, vedi l'esempio "Quota dinamica" riportato sopra.

Per informazioni sulla configurazione dei prodotti API con limiti di quota, consulta Gestire i prodotti API.

Configurazione dei contatori delle quote condivise

In genere, il criterio per le quote conteggia tutte le richieste inviate a un proxy API. Per alcuni casi d'uso, potresti voler applicare in modo forzato il conteggio della quota per le richieste in entrata, ma anche aumentare il conteggio delle quote per le risposte di destinazione che soddisfano una condizione specificata. Se utilizzati insieme, tre elementi dei criteri per le quote, <SharedName>, <CountOnly> e <EnforceOnly>, consentono di personalizzare il criterio per le quote per applicare la quota delle richieste in entrata e conteggiare le risposte di destinazione in base a una condizione da te specificata.

Ad esempio, supponi di voler aumentare il contatore della quota per un proxy API in cui le risposte della destinazione del backend hanno un codice di stato HTTP 200. Per ottenere questo conteggio specializzato:

  • Aggiungi un criterio per le quote al flusso di richiesta ProxyEndpoint con l'elemento <SharedName> impostato con un valore nome e l'elemento <EnforceOnly> impostato su true.
  • Aggiungi un altro criterio per le quote al flusso ProxyEndpoint Response con l'elemento <SharedName> impostato sullo stesso valore del nome del primo criterio e l'elemento <CountOnly> impostato su true.
  • Inserisci il secondo criterio per le quote (quello con <CountOnly>) in un passaggio condizionale che imposti la condizione in base alla quale incrementare il contatore della quota.

Per un esempio che mostra come utilizzare i contatori condivisi, consulta Contatori condivisi nella sezione Campioni.

Esempi

Questi esempi di codice dei criteri illustrano come iniziare e terminare i periodi di quota in base a:

Quota più dinamica

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

Le quote dinamiche ti consentono di configurare un singolo criterio per le quote che applica impostazioni di quota diverse in base alle informazioni passate al criterio per le quote. Un altro termine per le impostazioni della quota in questo contesto è piano di servizio. La quota dinamica controlla il piano di servizio dell'app e quindi applica queste impostazioni.

Ad esempio, quando crei un prodotto API, in via facoltativa, puoi impostare il limite di quota, l'unità di tempo e l'intervallo consentiti. Tuttavia, l'impostazione di questi valori nel prodotto API non ne forza l'utilizzo in un proxy API. Devi inoltre aggiungere un criterio per le quote al proxy API che legge questi valori. Per saperne di più, consulta Creare prodotti basati su API.

Nell'esempio precedente, il proxy API contenente il criterio per le quote utilizza un criterio VerifyAPIKey denominato verify-api-key per convalidare la chiave API passata in una richiesta. Il criterio per le quote accede alle variabili di flusso dal criterio VerifyAPIKey per leggere i valori della quota impostati sul prodotto API.

Un'altra opzione è impostare attributi personalizzati su singoli sviluppatori o app e quindi leggere questi valori nel criterio per le quote. Ad esempio, puoi impostare valori di quota diversi per sviluppatore. Puoi impostare attributi personalizzati per lo sviluppatore contenente il limite, l'unità di tempo e l'intervallo. Quindi, fai riferimento a questi valori nel criterio per le quote come mostrato di seguito:

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

Questo esempio utilizza anche le variabili di flusso VerificationAPIKey per fare riferimento agli attributi personalizzati impostati sullo sviluppatore.

Puoi utilizzare qualsiasi variabile per impostare i parametri del criterio per le quote. Queste variabili possono provenire da:

  • Variabili di flusso
  • Proprietà nel prodotto, nell'app o nello sviluppatore API
  • Una mappa chiave-valore (KVM)
  • Un'intestazione, un parametro di query, un parametro del modulo e altri

Per ogni proxy API, puoi aggiungere un criterio per le quote che faccia riferimento alla stessa variabile di tutti gli altri criteri per le quote in tutti gli altri proxy oppure il criterio per le quote può fare riferimento a variabili univoche per quel criterio e quel proxy.

Ora di inizio

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

Per una quota con type impostato su calendar, devi definire un valore <StartTime> esplicito. Il valore dell'ora corrisponde all'ora GMT, non all'ora locale. Se non fornisci un valore <StartTime> per un criterio di tipo calendar, Apigee emette un errore.

Il contatore delle quote per ogni app viene aggiornato in base ai valori <StartTime>, <Interval> e <TimeUnit>. Per questo esempio, il conteggio della quota inizia alle 10:30 GMT del 18 febbraio 2021 e si aggiorna ogni 5 ore. Pertanto, il prossimo aggiornamento è alle 15:30 GMT del 18 febbraio 2021.

Contatore accessi

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

Un proxy API ha accesso alle variabili di flusso impostate dal criterio per le quote. Puoi accedere a queste variabili di flusso nel proxy API per eseguire l'elaborazione condizionale, monitorare il criterio man mano che si avvicina al limite di quota, restituire il contatore della quota attuale a un'app o per altri motivi.

Poiché l'accesso alle variabili di flusso per il criterio si basa sull'attributo dei criteri name, per il criterio sopra denominato <Quota> puoi accedere alle variabili di flusso nel formato:

  • ratelimit.QuotaPolicy.allowed.count: conteggio consentito.
  • ratelimit.QuotaPolicy.used.count: valore del contatore corrente.
  • ratelimit.QuotaPolicy.expiry.time: ora UTC in cui viene reimpostato il contatore.

Esistono molte altre variabili di flusso a cui puoi accedere, come descritto di seguito.

Ad esempio, puoi utilizzare il seguente criterioAssignMessage per restituire i valori delle variabili di flusso della quota come intestazioni delle risposte:

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

Contatori condivisi

L'esempio seguente illustra come configurare un contatore condiviso per un proxy API, in cui il contatore delle quote viene incrementato anche quando la risposta di destinazione è in stato HTTP 200. Poiché entrambi i criteri per le quote utilizzano lo stesso valore <SharedName>, entrambi i criteri per le quote condivideranno lo stesso contatore delle quote. Per ulteriori informazioni, consulta Configurazione dei contatori delle quote condivise.

Esempio di configurazione 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>

Esempio di primo criterio per le quote:

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

Esempio di criterio per la seconda 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>

Prima richiesta

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

Utilizza questo codice campione per applicare una quota di 10.000 chiamate all'ora. Il criterio reimposta il contatore della quota nella parte superiore di ogni ora. Se il contatore raggiunge la quota di 10.000 chiamate prima della fine dell'ora, le chiamate oltre le 10.000 vengono rifiutate.

Ad esempio, se il contatore inizia da 2021-07-08 07:00:00, viene reimpostato su 0 alle ore 2021-07-08 08:00:00 (1 ora dall'ora di inizio). Se il primo messaggio viene ricevuto alle ore 2021-07-08 07:35:28 e il numero dei messaggi raggiunge 10.000 prima del giorno 2021-07-08 08:00:00, le chiamate oltre questo conteggio vengono rifiutate fino a quando il conteggio non viene reimpostato all'inizio dell'ora.

Il tempo di reimpostazione del contatore si basa sulla combinazione di <Interval> e <TimeUnit>. Ad esempio, se imposti <Interval> su 12 per <TimeUnit> di ora, il contatore viene reimpostato ogni dodici ore. Puoi impostare <TimeUnit> su minuto, ora, giorno, settimana o mese.

Puoi fare riferimento a questo criterio in più posizioni nel proxy API. Ad esempio, potresti inserirlo in Proxy PreFlow in modo che venga eseguito su ogni richiesta. In alternativa, puoi posizionarlo su più flussi nel proxy API. Se utilizzi questo criterio in più punti del proxy, avrà un unico contatore aggiornato da tutte le istanze del criterio.

In alternativa, puoi definire più criteri per le quote nel proxy API. Ogni criterio per le quote gestisce il proprio contatore, basato sull'attributo name del criterio.

Imposta identificatore

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

Per impostazione predefinita, un criterio per le quote definisce un singolo contatore per il proxy API, indipendentemente dall'origine di una richiesta. In alternativa, puoi utilizzare l'attributo <Identifier> con un criterio per le quote per mantenere contatori separati in base al valore dell'attributo <Identifier>.

Ad esempio, utilizza il tag <Identifier> per definire contatori separati per ogni ID client. Su una richiesta al proxy, l'app client passa quindi un'intestazione contenente clientID, come mostrato nell'esempio precedente.

Puoi specificare qualsiasi variabile di flusso per l'attributo <Identifier>. Ad esempio, puoi specificare che un parametro di query denominato id contiene l'identificatore univoco:

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

Se utilizzi il criterio VerifyAPIKey per convalidare la chiave API o i criteri OAuthV2 con i token OAuth, puoi utilizzare le informazioni nella chiave API o nel token per definire singoli contatori per lo stesso criterio per le quote. Ad esempio, il seguente elemento <Identifier> utilizza la variabile di flusso client_id di un criterio VerifyAPIKey denominato verify-api-key:

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

Ogni valore client_id univoco ora definisce il proprio contatore nel criterio per le quote.

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>

Puoi impostare i limiti di quota in modo dinamico utilizzando un conteggio delle quote basato su classi. In questo esempio, il limite di quota è determinato dal valore dell'intestazione developer_segment passata con ogni richiesta. Questa variabile può avere il valore platinum o silver. Se l'intestazione contiene un valore non valido, il criterio restituisce un errore di violazione della quota.

<Quota> elemento

Di seguito sono riportati gli attributi e gli elementi secondari di <Quota>. Tieni presente che alcune combinazioni di elementi si escludono a vicenda o non sono obbligatorie. Visualizza gli esempi per l'utilizzo specifico.

Le variabili verifyapikey.my-verify-key-policy.apiproduct.* riportate di seguito sono disponibili per impostazione predefinita quando viene utilizzato un criterio VerifyAPIKey denominato my-verify-key-policy per controllare la chiave API dell'app nella richiesta. I valori della variabile provengono dalle impostazioni di quota sul prodotto API a cui è associata la chiave, come descritto in Recupero delle impostazioni di quota dalla configurazione del prodotto 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>

I seguenti attributi sono specifici di questo criterio:

Attributo Descrizione Predefinita Presenza
Tipo

Imposta il tipo di criterio per le quote, che determina quando e come il contatore delle quote controlla l'utilizzo della quota e le modalità di reimpostazione.

Se non imposti type, il contatore inizia all'inizio del minuto/ora/giorno/settimana/mese.

I valori validi sono:

  • calendar
  • rollingwindow
  • flexi

Per una descrizione completa di ciascun tipo, consulta Tipi di criteri per le quote.

 N/A Facoltativo

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/A Obbligatorio
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche:

 false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

 true Facoltativo
async

Questo attributo è obsoleto.

 false Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

<Allow>

Specifica il limite di conteggio per la quota. Se il contatore per il criterio raggiunge questo valore limite, le chiamate successive vengono rifiutate fino a quando il contatore non viene reimpostato.

Può contenere anche un elemento <Class> che condiziona l'elemento <Allow> in base a una variabile di flusso.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo di numero intero o complesso
Elemento principale <Quota>
Elementi secondari <Class>

Di seguito sono riportati tre modi per impostare l'elemento <Allow>:

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

Se specifichi sia count sia countRef, countRef ha la priorità. Se countRef non si risolve in fase di runtime, viene utilizzato il valore di count.

Puoi anche specificare un elemento <Class> come elemento secondario di <Allow> per determinare il conteggio consentito del criterio in base a una variabile di flusso. Apigee abbina il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

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

La seguente tabella elenca gli attributi di <Allow>:

Attributo Descrizione Predefinita Presenza
count

Utilizzalo per specificare un conteggio dei messaggi per la quota.

Ad esempio, un valore dell'attributo count pari a 100, Interval pari a 1 e un valore TimeUnit del mese specificano una quota di 100 messaggi al mese.

 2000 Facoltativo
countRef

Utilizzalo per specificare una variabile di flusso contenente il conteggio dei messaggi per una quota. countRef ha la precedenza sull'attributo count.

 nessuno Facoltativo

<Class>

Consente di condizionare il valore dell'elemento <Allow> in base al valore di una variabile di flusso. Per ogni diverso tag secondario <Allow> di <Class>, il criterio mantiene un contatore diverso.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Allow>
Elementi secondari <Allow> (figlio di <Class>)

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando l'attributo ref per l'elemento <Class>. Apigee utilizza quindi il valore della variabile di flusso per selezionare uno degli elementi secondari <Allow> al fine di determinare il conteggio consentito del criterio. Apigee abbina il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

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

In questo esempio, il contatore della quota corrente è determinato dal valore del parametro di query time_variable passato con ogni richiesta. Questa variabile può avere un valore peak_time o off_peak_time. Se il parametro di query contiene un valore non valido, il criterio restituisce un errore di violazione della quota.

La seguente tabella elenca gli attributi di <Class>:

Attributo Descrizione Predefinita Presenza
riferimento Consente di specificare una variabile di flusso contenente la classe di quota per una quota. nessuno Obbligatorio

<Allow> (figlio di <Class>)

Specifica il limite per un contatore delle quote definito dall'elemento <Class>. Per ogni tag secondario <Allow> diverso di <Class>, il criterio mantiene un contatore diverso.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Class>
Elementi secondari Nessuna

Ad esempio:

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

In questo esempio, il criterio per le quote gestisce due contatori delle quote denominati peak_time e off_peak_time. Quale di questi viene utilizzato dipende dal parametro di query trasmesso, come mostrato nell'esempio di <Class>.

La seguente tabella elenca gli attributi di <Allow>:

Attributo Descrizione Predefinita Presenza
classe Definisce il nome del contatore della quota. nessuno Obbligatorio
count Specifica il limite di quota per il contatore. nessuno Obbligatorio

<Interval>

Specifica il numero di periodi di tempo in cui vengono calcolate le quote.

Valore predefinito n/d
Obbligatorio? Obbligatorio
Tipo Integer
Elemento principale <Quota>
Elementi secondari Nessuna

Utilizzalo per specificare un numero intero (ad esempio 1, 2, 5, 60 e così via) che verrà accoppiato all'elemento <TimeUnit> specificato (minuto, ora, giorno, settimana o mese) per determinare un periodo di tempo durante il quale Apigee calcola l'utilizzo della quota.

Ad esempio, un intervallo di 24 con <TimeUnit> di hour indica che la quota verrà calcolata nell'arco di 24 ore.

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

La seguente tabella elenca gli attributi di <Interval>:

Attributo Descrizione Predefinita Presenza
riferimento

Utilizzalo per specificare una variabile di flusso contenente l'intervallo per una quota. ref ha la precedenza su un valore di intervallo esplicito. Se sono specificati sia riferimento che valore, il riferimento ha la priorità. Se ref non si risolve in fase di runtime, viene utilizzato il valore.

 nessuno Facoltativo

<TimeUnit>

Specifica l'unità di tempo applicabile alla quota.

Valore predefinito n/d
Obbligatorio? Obbligatorio
Tipo String
Elemento principale <Quota>
Elementi secondari Nessuna

Seleziona tra minute, hour, day, week, month o year.

Ad esempio, un valore Interval di 24 con un valore TimeUnit di hour significa che la quota verrà calcolata nell'arco di 24 ore.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Predefinita: nessuno
Presenza: Obbligatorio
Tipo: String

La seguente tabella elenca gli attributi di <TimeUnit>:

Attributo Descrizione Predefinita Presenza
riferimento Specifica una variabile di flusso contenente l'unità di tempo per una quota. ref ha la precedenza su un valore di intervallo esplicito. Se ref non si risolve in fase di runtime, viene utilizzato il valore dell'intervallo. nessuno Facoltativo

<StartTime>

Se il criterio type viene impostato su calendar, consente di specificare la data e l'ora in cui inizia il conteggio del contatore delle quote, a prescindere dal fatto che siano state ricevute richieste da eventuali app.

Valore predefinito n/d
Obbligatorio? Facoltativa (obbligatoria quando il criterio type è impostato su calendar)
Tipo Stringa nel formato di data e ora ISO 8601
Elemento principale <Quota>
Elementi secondari Nessuna

Devi fornire un valore <StartTime> esplicito quando type è impostato su calendar; non puoi utilizzare un riferimento a una variabile di flusso. Se specifichi un valore <StartTime> quando non è impostato alcun valore di type, Apigee restituisce un errore.

Ad esempio:

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

<Distributed>

Determina se Apigee utilizza uno o più nodi per elaborare le richieste.

Valore predefinito false
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <Quota>
Elementi secondari Nessuna

Imposta su true per specificare che il criterio deve mantenere un contatore centrale e sincronizzarlo continuamente su tutti i nodi. I nodi possono trovarsi in zone di disponibilità e/o regioni diverse.

Se utilizzi il valore predefinito false, potresti superare la quota perché il conteggio per ciascun nodo non è condiviso:

<Distributed>false</Distributed>

Per garantire che i contatori siano sincronizzati e aggiornati a ogni richiesta, imposta <Distributed> e <Synchronous> su true:

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

<Synchronous>

Determina se aggiornare in modo sincrono un contatore di quota distribuita.

Valore predefinito false
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <Quota>
Elementi secondari Nessuna

Imposta su true per aggiornare un contatore di quota distribuita in modo sincrono. Ciò significa che gli aggiornamenti dei contatori vengono effettuati nello stesso momento in cui viene controllata la quota in una richiesta all'API. Imposta su true se è essenziale non consentire chiamate API oltre la quota.

Imposta su false per aggiornare il contatore della quota in modo asincrono. Ciò significa che è possibile che alcune chiamate API che superano la quota vengano andate a buon fine, a seconda di quando il contatore delle quote nel repository centrale viene aggiornato in modo asincrono. Tuttavia, non dovrai affrontare il potenziale impatto sulle prestazioni associato agli aggiornamenti sincroni.

L'intervallo di aggiornamento asincrono predefinito è di 10 secondi. Utilizza l'elemento <AsynchronousConfiguration> per configurare questo comportamento asincrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura l'intervallo di sincronizzazione tra i contatori delle quote distribuite quando l'elemento di configurazione dei criteri <Synchronous> non è presente o non è presente e è impostato su false. Apigee ignora questo elemento quando <Synchronous> è impostato su true.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Quota>
Elementi secondari <SyncIntervalInSeconds>
<SyncMessageCount>

Puoi specificare il comportamento di sincronizzazione utilizzando gli elementi secondari <SyncIntervalInSeconds> o <SyncMessageCount>. Utilizza uno o entrambi gli elementi. Ad esempio,

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

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Quando è presente solo <SyncIntervalInSeconds>, la quota si sincronizza ogni N secondi, dove N è il valore specificato nell'elemento, indipendentemente dal numero di messaggi gestiti.
  • Quando è presente solo <SyncMessageCount>, la quota sincronizza ogni messaggio M, dove M è il valore specificato nell'elemento, oppure ogni 10 secondi, a seconda dell'evento che si verifica per primo.
  • Quando sono presenti entrambi gli elementi, la quota sincronizza ogni messaggio M o ogni N secondi, a seconda dell'evento che si verifica per primo.
  • Quando <AsynchronousConfiguration> non è presente o non è presente nessun elemento secondario, la quota si sincronizza ogni 10 secondi, indipendentemente dal numero di messaggi gestiti.

<SyncIntervalInSeconds>

Sostituisce il comportamento predefinito in cui gli aggiornamenti asincroni vengono eseguiti dopo un intervallo di 10 secondi.

Valore predefinito 10 secondi
Obbligatorio? Facoltativo
Tipo Integer
Elemento principale <AsynchronousConfiguration>
Elementi secondari Nessuna
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

L'intervallo di sincronizzazione deve essere maggiore o uguale a 10 secondi, come descritto in Limiti.

<SyncMessageCount>

Specifica il numero di richieste da elaborare prima di sincronizzare il contatore della quota.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Integer
Elemento principale <AsynchronousConfiguration>
Elementi secondari Nessuna
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Utilizzando la configurazione in questo esempio, su ogni nodo il conteggio delle quote verrà sincronizzato ogni 5 richieste o ogni 10 secondi, a seconda dell'evento che si verifica per primo.

<Identifier>

Configura il criterio per creare contatori unici basati su una variabile di flusso.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo String
Elemento principale <Quota>
Elementi secondari Nessuna

Tramite l'elemento Identifier, puoi assegnare i conteggi delle chiamate a bucket distinti definiti dal valore in una variabile di flusso. Ad esempio, puoi utilizzare la variabile developer.id, che viene compilata dopo un criterioVerifyAPIKey, per applicare un limite di quota a tutte le istanze di tutte le app create da ogni sviluppatore specifico oppure puoi utilizzare client_id per applicare un limite di quota per ogni app specifica. La configurazione di quest'ultima ha il seguente aspetto:

<Identifier ref="client_id"/>

Puoi fare riferimento a una variabile personalizzata che potresti impostare con il criterioAssignMessage o al criterio JavaScript oppure a una variabile impostata implicitamente, come quelle impostate dal criterioVerifyAPIKey o dal criterio VerifyJWT. Per ulteriori informazioni sulle variabili, consulta Utilizzo delle variabili di flusso e per un elenco di variabili note definite da Apigee, consulta la pagina di riferimento sulle variabili di flusso.

Se non utilizzi questo elemento, il criterio assegna tutti i conteggi delle chiamate in un unico contatore per il criterio per le quote specifico.

Questo elemento viene discusso anche in Come funziona il criterio per le quote quando non viene specificato alcun identificatore?

Nella tabella seguente vengono descritti gli attributi di <Identifier>:

Attributo Descrizione Predefinita Presenza
riferimento

Specifica una variabile di flusso che identifica il contatore da utilizzare per la richiesta. La variabile può fare riferimento a un'intestazione HTTP, un parametro di query, un parametro del modulo o un elemento dei contenuti del messaggio oppure un altro valore per identificare come assegnare i conteggi delle chiamate.

La variabile client_id viene comunemente utilizzata come variabile. client_id è anche noto come chiave API o chiave consumer e viene generato per un'app quando è registrata in un'organizzazione su Apigee. Puoi utilizzare questo identificatore se hai abilitato criteri della chiave API o di autorizzazione OAuth per l'API.

 N/A Facoltativo

<MessageWeight>

Specifica il costo assegnato a ciascun messaggio ai fini della quota. Utilizza questo elemento per aumentare l'impatto dei messaggi di richiesta che, ad esempio, consumano più risorse di calcolo di altri.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Integer
Elemento principale <Quota>
Elementi secondari Nessuna

Ad esempio, se vuoi conteggiare POST messaggi sono il doppio più costosi rispetto a GET messaggi. Di conseguenza, imposti <MessageWeight> su 2 per POST e 1 per GET. Puoi anche impostare <MessageWeight> su 0 in modo che la richiesta non influisca sul contatore.

In questo esempio, se la quota è di 10 messaggi al minuto e il valore <MessageWeight> per le richieste POST è 2, la quota consentirà 5 richieste POST in qualsiasi intervallo di 10 minuti. Eventuali richieste aggiuntive, POST o GET, prima della reimpostazione del contatore vengono rifiutate.

Un valore che rappresenta <MessageWeight> deve essere specificato da una variabile di flusso e può essere estratto da intestazioni HTTP, parametri di ricerca, un payload di richiesta XML o JSON o qualsiasi altra variabile di flusso. Ad esempio, puoi impostarlo in un'intestazione denominata weight:

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

Definisce le impostazioni delle quote per un prodotto API, come le unità di tempo, l'intervallo e il valore massimo consentito.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Quota>
Elementi secondari <DefaultConfig>

Se aggiungi l'elemento <UseQuotaConfigInAPIProduct> al criterio per le quote, Apigee ignora tutti gli elementi secondari <Allow>, <Interval> e <TimeUnit> di <Quota>.

L'elemento <UseQuotaConfigInAPIProduct> è semplicemente un contenitore per le impostazioni predefinite che definisci utilizzando l'elemento <DefaultConfig>, come mostrato nell'esempio seguente:

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

Puoi utilizzare l'attributo stepName per fare riferimento a un criterioVerifyAPIKey o a un'operazione del criterio ValidateToken del criterio OAuthv2 nel flusso.

Nella tabella seguente vengono descritti gli attributi di <UseQuotaConfigInAPIProduct>:

Attributo Descrizione Predefinita Presenza
stepName Identifica il nome del criterio di autenticazione nel flusso. La destinazione può essere un criterio VerificationAPIKey o un criterio OAuthv2. N/A Obbligatorio

Per ulteriori informazioni, consulta le seguenti risorse:

<DefaultConfig>

Contiene valori predefiniti per la quota di un prodotto API. Quando definisci un valore <DefaultConfig>, sono obbligatori tutti e tre gli elementi secondari.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <UseQuotaConfigInAPIProduct>
Elementi secondari <Allow>
<Interval>
<TimeUnit>

È possibile definire questi valori sia sul funzionamento del prodotto API (con l'interfaccia utente sia con l'API dei prodotti API e nei criteri per le quote. In questo caso, tuttavia, le impostazioni sul prodotto API hanno la precedenza e quelle sui criteri per le quote vengono ignorate.

La sintassi di questo elemento è la seguente:

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

L'esempio seguente specifica una quota di 10.000 ogni settimana:

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

Per ulteriori informazioni, consulta le seguenti risorse:

<SharedName>

Identifica questo criterio per le quote come condiviso. Tutti i criteri per le quote in un proxy API con lo stesso valore <SharedName> condividono lo stesso contatore di quote di base. Se questo elemento è presente, devono essere presenti anche gli elementi <EnforceOnly> o <CountOnly>.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori delle quote condivise.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo String
Elemento principale <Quota>
Elementi secondari Nessuna

<CountOnly>

Inserisci un criterio per le quote con questo elemento impostato su true in un passaggio condizionale nel flusso di risposta ProxyEndpoint per incrementare in modo condizionale il contatore della quota sottostante. Se questo elemento è presente, devono essere presenti anche gli elementi <SharedName> e <EnforceOnly>.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori delle quote condivise.

Valore predefinito false
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <Quota>
Elementi secondari Nessuna

<EnforceOnly>

Inserisci un criterio per le quote con questo elemento impostato su true nel flusso di richieste di un proxy API. Questa configurazione consente di condividere i conteggi delle quote per qualsiasi criterio per le quote nel proxy API con lo stesso valore <SharedName>. Se questo elemento è presente, devono essere presenti anche gli elementi <SharedName> e <CountOnly>.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori delle quote condivise.

Valore predefinito false
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <Quota>
Elementi secondari Nessuna

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando viene eseguito un criterio per le quote. Per saperne di più, consulta Riferimento per le variabili di flusso.

Variabili Tipo Autorizzazioni Descrizione
ratelimit.{policy_name}.allowed.count Lungo Sola lettura Restituisce il conteggio della quota consentito.
ratelimit.{policy_name}.used.count Lungo Sola lettura Restituisce la quota corrente utilizzata in un intervallo di quota.
ratelimit.{policy_name}.available.count Lungo Sola lettura Restituisce il conteggio della quota disponibile nell'intervallo di quota.
ratelimit.{policy_name}.exceed.count Lungo Sola lettura Restituisce 1 dopo il superamento della quota.
ratelimit.{policy_name}.total.exceed.count Lungo Sola lettura Restituisce 1 dopo il superamento della quota.
ratelimit.{policy_name}.expiry.time Lungo Sola lettura

Restituisce il tempo UTC (in millisecondi), che determina quando scade la quota e quando inizia il nuovo intervallo di quota.

Se il tipo di criterio per le quote è rollingwindow, questo valore non è valido perché l'intervallo di quota non ha scadenza.
ratelimit.{policy_name}.identifier String Sola lettura Restituisce il riferimento dell'identificatore (client) associato al criterio
ratelimit.{policy_name}.class String Sola lettura Restituisce la classe associata all'identificatore cliente
ratelimit.{policy_name}.class.allowed.count Lungo Sola lettura Restituisce il conteggio delle quote consentito definito nella classe
ratelimit.{policy_name}.class.used.count Lungo Sola lettura Restituisce la quota utilizzata all'interno di una classe
ratelimit.{policy_name}.class.available.count Lungo Sola lettura Restituisce il conteggio delle quote disponibili nella classe
ratelimit.{policy_name}.class.exceed.count Lungo Sola lettura Restituisce il conteggio delle richieste che supera il limite della classe nell'intervallo di quota attuale
ratelimit.{policy_name}.class.total.exceed.count Lungo Sola lettura Restituisce il conteggio totale delle richieste che supera il limite nella classe in tutti gli intervalli di quota, pertanto è la somma di class.exceed.count per tutti gli intervalli di quota.
ratelimit.{policy_name}.failed Booleano Sola lettura

Indica se il criterio ha avuto esito negativo (vero o falso).

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa Correggi
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Si verifica se l'elemento <Interval> non è definito nel criterio Quota. Questo elemento è obbligatorio e utilizzato per specificare l'intervallo di tempo applicabile alla quota. L'intervallo di tempo può essere minuti, ore, giorni, settimane o mesi, come definito dall'elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Si verifica se l'elemento <TimeUnit> non è definito nel criterio Quota. Questo elemento è obbligatorio e utilizzato per specificare l'unità di tempo applicabile alla quota. L'intervallo di tempo può essere espresso in minuti, ore, giorni, settimane o mesi.
policies.ratelimit.InvalidMessageWeight 500 Si verifica se il valore dell'elemento <MessageWeight> specificato tramite una variabile di flusso non è valido (un valore non intero).
policies.ratelimit.QuotaViolation 500 Il limite di quota è stato superato. N/A

Errori di deployment

Nome errore Causa Correggi
InvalidQuotaInterval Se l'intervallo di quota specificato nell'elemento <Interval> non è un numero intero, il deployment del proxy API non va a buon fine. Ad esempio, se l'intervallo di quota specificato è 0,1 nell'elemento <Interval>, il deployment del proxy API non riesce.
InvalidQuotaTimeUnit Se l'unità di tempo specificata nell'elemento <TimeUnit> non è supportata, il deployment del proxy API non va a buon fine. Le unità di tempo supportate sono minute, hour, day, week e month.
InvalidQuotaType Se il tipo di quota specificato dall'attributo type nell'elemento <Quota> non è valido, il deployment del proxy API non va a buon fine. I tipi di quota supportati sono default, calendar, flexi e rollingwindow.
InvalidStartTime Se il formato dell'ora specificato nell'elemento <StartTime> non è valido, il deployment del proxy API non va a buon fine. Il formato valido è yyyy-MM-dd HH:mm:ss, ovvero il formato di data e ora ISO 8601. Ad esempio, se il tempo specificato nell'elemento <StartTime> è 7-16-2017 12:00:00, il deployment del proxy API non va a buon fine.
StartTimeNotSupported Se viene specificato l'elemento <StartTime> il cui tipo di quota non è di tipo calendar, il deployment del proxy API non va a buon fine. L'elemento <StartTime> è supportato solo per il tipo di quota calendar. Ad esempio, se l'attributo type è impostato su flexi o rolling window nell'elemento <Quota>, il deployment del proxy API non va a buon fine.
InvalidTimeUnitForDistributedQuota Se l'elemento <Distributed> è impostato su true e l'elemento <TimeUnit> è impostato su second, il deployment del proxy API non va a buon fine. L'unità di tempo second non è valida per una quota distribuita.
InvalidSynchronizeIntervalForAsyncConfiguration Se il valore specificato per l'elemento <SyncIntervalInSeconds> all'interno dell'elemento <AsynchronousConfiguration> in un criterio Quota è inferiore a zero, il deployment del proxy API non riesce.
InvalidAsynchronizeConfigurationForSynchronousQuota Se il valore dell'elemento <AsynchronousConfiguration> è impostato su true in un criterio Quota in cui è definita anche la configurazione asincrona mediante l'elemento <AsynchronousConfiguration>, il deployment del proxy API non riesce.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. ratelimit.QT-QuotaPolicy.failed = true

Esempio di risposta di errore

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

Esempio di regola di errore

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

Schema

Argomenti correlati

Criterio ResetQuota

Criterio di SpikeArrest

Confronto tra i criteri per quota e Spike Arrest