Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Panoramica
Una quota è un'assegnazione di messaggi di richiesta che un proxy API può gestire in un periodo di tempo, ad esempio minuti, ore, giorni, settimane o mesi. Il criterio per le quote gestisce i contatori che conteggiano 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 determinato intervallo di tempo. Utilizzando i criteri di quota, ad esempio, puoi limitare le app a 1 richiesta al minuto o a 10.000 richieste al mese.
Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare 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 Tipi di criteri.
Ad esempio, se una quota è definita come 10.000 messaggi al mese, il limite di velocità inizia dopo il 10.000° messaggio. Non importa se i 10.000 messaggi sono stati conteggiati il primo giorno o l'ultimo giorno del periodo; non sono consentite richieste aggiuntive finché il contatore della quota non viene reimpostato automaticamente al termine dell'intervallo di tempo specificato o finché la quota non viene reimpostata esplicitamente utilizzando il criterio ResetQuota.
Una variante del criterio Quota, il criterio SpikeArrest, impedisce i picchi (o le esplosioni) di traffico che possono essere causati da un improvviso aumento dell'utilizzo, da client con bug o da attacchi dannosi.
Utilizza il criterio per le quote per configurare il numero di messaggi di richiesta consentiti da un proxy API in un determinato periodo di tempo, ad esempio un minuto, un'ora, un giorno, una settimana o un mese. Puoi impostare la quota in modo che sia uguale per tutte le app che accedono al proxy API oppure 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 dagli picchi di traffico complessivi. A tale scopo, utilizza il criterio SpikeArrest.
Video
Questi video illustrano la gestione delle quote con le norme relative alle quote:
Introduzione
Quota dinamica
Distribuiti e sincroni
Peso del messaggio
Calendar
Finestra temporale continua
Flexi
Quota condizionale
Variabili di flusso
Gestione degli errori
Tipi di criteri per le quote
Il criterio di quota supporta diversi modi in cui il contatore della quota viene avviato e reimpostato.
Puoi definire quale utilizzare con l'attributo type
nell'elemento <Quota>
, come mostrato 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 della quota per ogni app viene aggiornato in base ai valori di<StartTime>
,<Interval>
e<TimeUnit>
impostati.rollingwindow
: configura una quota che utilizza una "finestra mobile" per determinare l'utilizzo della quota. Conrollingwindow
, puoi determinare le dimensioni della finestra con gli elementi<Interval>
e<TimeUnit>
, ad esempio 1 giorno. Quando arriva una richiesta, Apigee controlla l'ora esatta della richiesta (ad es. 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 questo intervallo.flexi
: configura una quota che fa iniziare il contatore quando viene ricevuto il primo messaggio di richiesta da un'app e lo reimposta in base ai valori<Interval>
e<TimeUnit>
.
La seguente tabella descrive i ripristini delle quote per ciascun tipo:
Unità di tempo | Tipo | ||
---|---|---|---|
default (o null) |
calendar |
flexi |
|
minuto | Inizio del minuto successivo | Un minuto dopo le <StartTime> |
Un minuto dopo la prima richiesta |
ora | All'inizio della prossima ora | Un'ora dopo le <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 di 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 con finestra scorrevole
funzionano impostando la dimensione di una finestra della quota, ad esempio una finestra di un'ora o un giorno.
Quando viene inviata una nuova richiesta, il criterio determina se la quota è stata superata nel periodo di tempo precedente.
Ad esempio, definisci un intervallo di due ore che consente 1000 richieste. Una nuova richiesta viene inviata alle 16:45.Il criterio calcola il conteggio delle quote per l'intervallo di due ore precedente, ovvero il numero di richieste ricevute dalle 14:45. Se il limite di quota non è stato superato in questo intervallo di due ore, la richiesta è consentita.
Un minuto dopo, alle 16:46, arriva un'altra richiesta. Ora il criterio calcola il conto della quota dalle 14:46 per determinare se il limite è stato superato.
Per il tipo rollingwindow
, il contatore non viene mai reimpostato, ma viene rielaborato a ogni richiesta.
Informazioni sui contatori delle quote
Quando un criterio per le quote viene eseguito in un flusso di proxy API, un 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 di quota può utilizzare uno o più contatori. È importante capire quando vengono utilizzati più contatori e come si comportano.
Come vengono conteggiate le quote per i prodotti API
Se il proxy API è incluso in un prodotto API, puoi configurare il criterio di quota in modo da utilizzare le regole di quota definite in quel prodotto. Un prodotto API può specificare regole di quota a livello di prodotto o a livello di singole operazioni.
Viene mantenuto un contatore delle quote separato per ogni operazione definita in un prodotto API e vengono rispettate le seguenti regole:
- Se per un'operazione è stata definita una quota, le regole di quota dell'operazione hanno la precedenza sulle regole di quota definite a livello di prodotto. Per ogni operazione viene creato un contatore delle quote distinto. Qualsiasi chiamata API al percorso di un'operazione incrementa il relativo contatore.
- Se per un'operazione non è stata definita una quota, viene applicata la regola di quota a livello di prodotto. Tuttavia, per l'operazione viene comunque mantenuto un contatore delle quote separato. In questo caso è importante capire che, anche se la regola della quota viene presa dalla definizione a livello di prodotto, l'operazione mantiene comunque il proprio contatore.
- Se il prodotto API non include definizioni di quote, né a livello di prodotto né di operazione, vengono applicate le regole di quota specificate nel criterio. Tuttavia, anche in questo caso, viene mantenuto un contatore delle quote separato per ogni operazione nel prodotto API.
Le sezioni seguenti descrivono in modo più dettagliato 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 è condivisa da tutte le operazioni per le quali non è stata specificata una quota. 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
associate allo stesso proxy e che non dispongono di un proprio contatore condivideranno lo stesso
contatore delle quote impostato a livello di prodotto API.
Nella Figura 1, le operazioni 1 e 2
sono associate a Proxy1 e le operazioni 4 e 5 sono associate a Proxy3. Poiché
quotaCounterScope=PROXY
è impostato nel prodotto API, ciascuna di queste operazioni condivide l'impostazione della quota a livello di prodotto API. Tieni presente che, sebbene queste operazioni condividano la stessa configurazione della quota, utilizzano contatori separati in base all'associazione del proxy. D'altra
parte, l'operazione 3 ha una propria configurazione della quota impostata e pertanto non è interessata dal
flag quotaCounterScope
.
Figura 1: utilizzo del flag quotaCounterScope
Per impostazione predefinita, se per un'operazione non è stata definita una quota, viene applicata la regola della quota a livello di prodotto. Tuttavia, per l'operazione viene comunque mantenuto un contatore delle quote separato.
Come vengono conteggiate le quote se non sono in uso prodotti API
Se non è associato alcun prodotto API a un proxy API, un criterio per le quote gestisce un singolo contatore, indipendentemente dal numero di volte in cui viene fatto riferimento in un proxy API. Il nome del contatore delle quote si basa sull'attributo name
del criterio.
Ad esempio, crei un criterio di quota denominato MyQuotaPolicy
con un limite di 5 richieste e lo inserisci in più flussi (flusso A, B e C) nel proxy API. Anche se viene utilizzato in più flussi, mantiene un singolo contatore aggiornato da tutte le istanze del criterio:
- Viene eseguito il flusso A -> Viene eseguito MyQuotaPolicy e il relativo contatore = 1
- Viene eseguito il flusso B -> viene eseguito MyQuotaPolicy e il relativo contatore = 2
- Viene eseguito il flusso A -> viene eseguito MyQuotaPolicy e il relativo contatore = 3
- Viene eseguito il flusso C -> viene eseguito MyQuotaPolicy e il relativo contatore = 4
- Viene eseguito il flusso A -> Viene eseguito MyQuotaPolicy e il relativo contatore = 5
La richiesta successiva a uno dei tre flussi viene rifiutata perché il contatore delle quote ha raggiunto il suo limite.
L'utilizzo dello stesso criterio per le quote in più di un punto in un flusso di proxy API, che può causare involontariamente l'esaurimento della quota più rapidamente del previsto, è un antipattern descritto in Introduzione agli antipattern.
In alternativa, puoi definire più criteri per le quote nel proxy API e utilizzare un criterio diverso in ogni flusso. Ogni criterio di quota gestisce il proprio contatore in base all'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 unici in un unico criterio. Utilizzando questi elementi, un singolo criterio può gestire contatori diversi in base all'app che effettua la richiesta, allo sviluppatore dell'app che effettua la richiesta, a un ID client o a un altro identificatore client e altro ancora. Consulta gli esempi riportati sopra per ulteriori informazioni sull'utilizzo degli elementi <Class>
o <Identifier>
.
Notazione del tempo
Tutti gli orari della quota sono impostati sul fuso orario UTC (Coordinated Universal Time).
La notazione dell'ora della quota segue la notazione della data standard internazionale definita nello standard internazionale ISO 8601.
Le date sono definite come 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 come ore, minuti e secondi nel seguente formato:
hours:minutes:seconds
. Ad esempio, 23:59:59
rappresenta la data e l'ora un
secondo prima di mezzanotte.
Tieni presente che sono disponibili due notazioni, 00:00:00
e 24:00:00
, per distinguere i due mezzenotti che possono essere associati a una data. Pertanto, 2021-02-04
24:00:00
corrisponde alla stessa data e alla stessa ora di 2021-02-05 00:00:00
. Quest'ultima è solitamente la notazione preferita.
Ottenere le impostazioni di quota dalla configurazione del prodotto API
Puoi impostare limiti di quota nelle configurazioni dei prodotti API. Questi limiti non applicano automaticamente la quota. In alternativa, puoi fare riferimento alle impostazioni della quota dei prodotti in un criterio di quota. Ecco alcuni vantaggi dell'impostazione di una quota per il prodotto da utilizzare come riferimento per i criteri di quota:
- I criteri per le quote possono utilizzare un'impostazione uniforme in tutti i proxy API del prodotto API.
- Puoi apportare modifiche di runtime all'impostazione della quota in un prodotto API e i criteri di quota che fanno riferimento al valore vengono aggiornati automaticamente.
Per ulteriori informazioni sull'utilizzo delle impostazioni di quota da un prodotto API, consulta l'esempio "Quota dinamica" sopra.
Per informazioni sulla configurazione dei prodotti API con limiti di quota, consulta Gestione dei 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,
potrebbe essere opportuno applicare il conteggio della quota delle richieste in entrata, ma anche incrementare il conteggio della quota per
le risposte target che soddisfano una condizione specificata.
Se li utilizzi insieme, tre elementi dei criteri per le quote, <SharedName>
, <CountOnly>
e <EnforceOnly>
, ti consentono di personalizzare i criteri per le quote in modo da applicare la quota delle richieste in arrivo e conteggiare le risposte target in base a una condizione specificata.
Ad esempio, supponiamo che tu voglia incrementare il contatore delle quote per un proxy API in cui le risposte del backend di destinazione hanno un codice di stato HTTP 200
. Per eseguire questo conteggio specializzato:
- Aggiungi un criterio di quota al flusso di richieste ProxyEndpoint con l'elemento
<SharedName>
impostato su un valore name e l'elemento<EnforceOnly>
impostato sutrue
. - Aggiungi un altro criterio di quota al flusso di risposta ProxyEndpoint con l'elemento
<SharedName>
impostato sullo stesso valore del nome del primo criterio e l'elemento<CountOnly>
impostato sutrue
. - Inserisci la seconda regola di quota (quella con
<CountOnly>
) in un passaggio condizionale che imposta 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 Samples.
Esempi
Questi esempi di codice delle norme mostrano 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 di quota che applica impostazioni di quota diverse in base alle informazioni trasmesse al criterio di quota. Un altro termine per le impostazioni di quota in questo contesto è piano di servizio. La quota dinamica controlla il piano di servizio delle app e poi applica queste impostazioni.
Ad esempio, quando crei un prodotto API, puoi impostare facoltativamente il limite, l'unità di tempo e l'intervallo della quota consentita. Tuttavia, l'impostazione di questi valori nel prodotto API non ne impone l'utilizzo in un proxy API. Devi anche aggiungere un criterio di quota al proxy API che legga questi valori. Per saperne di più, consulta Creare prodotti 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 Quota accede quindi alle variabili di flusso del criterio VerifyAPIKey per leggere i valori
della quota impostati sul prodotto API.
Un'altra opzione consiste nell'impostare attributi personalizzati su singoli sviluppatori o app e poi leggere questi valori nel criterio di quota. Ad esempio, per impostare valori di quota diversi per sviluppatore, imposta attributi personalizzati sullo sviluppatore contenenti il limite, l'unità di tempo e l'intervallo. Poi 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 VerifyAPIKey per fare riferimento agli attributi personalizzati impostati sullo sviluppatore.
Puoi utilizzare qualsiasi variabile per impostare i parametri del criterio Quota. Queste variabili possono essere ricavate da:
- Variabili di flusso
- Proprietà del prodotto API, dell'app o dello sviluppatore
- Una mappa chiave-valore (KVM)
- Un'intestazione, un parametro di query, un parametro di modulo e altri
Per ogni proxy API, puoi aggiungere un criterio per le quote che fa 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 è l'ora GMT, non l'ora locale. Se non fornisci un valore <StartTime>
per un criterio di tipo
calendar
, Apigee genera un errore.
Il contatore delle quote per ogni app viene aggiornato in base ai valori <StartTime>
,
<Interval>
e <TimeUnit>
. In questo
esempio, la quota inizia a essere conteggiata alle 10:30 GMT del 18 febbraio 2021 e si aggiorna ogni
5 ore. Di conseguenza, il prossimo aggiornamento è previsto per le 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 quando si avvicina al limite di quota, restituire il contatore della quota corrente a un'app o per altri motivi.
Poiché l'accesso alle variabili di flusso per il criterio si basa sull'attributo name
dei criteri, per il criterio denominato <Quota>
sopra riportato accedono alle relative variabili di flusso nel seguente modo:
ratelimit.QuotaPolicy.allowed.count
: numero consentito.ratelimit.QuotaPolicy.used.count
: valore corrente del contatore.ratelimit.QuotaPolicy.expiry.time
: ora UTC in cui il contatore viene reimpostato.
Puoi accedere a molte altre variabili di flusso, come descritto di seguito.
Ad esempio, puoi utilizzare il seguente criterio AssignMessage per restituire i valori delle variabili del flusso di quote come intestazioni di risposta:
<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 è lo stato HTTP 200
.
Poiché entrambi i criteri per le quote utilizzano lo stesso valore <SharedName>
, entrambi condivideranno lo stesso contatore delle quote. Per saperne di più, consulta Configurare i contatori delle quote condivise.
Esempio di configurazione di 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>
Primo esempio di norma sulla 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>
Secondo esempio di criteri per le quote:
<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 delle quote all'inizio 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 a 2021-07-08 07:00:00
, viene reimpostato su
0 alle 2021-07-08 08:00:00
(1 ora dall'ora di inizio). Se il primo messaggio viene ricevuto alle 2021-07-08 07:35:28
e il conteggio dei messaggi raggiunge 10.000 prima delle 2021-07-08 08:00:00
, le chiamate oltre questo numero vengono rifiutate fino al ripristino del conteggio all'inizio dell'ora.
L'ora di reimpostazione del contatore si basa sulla combinazione di <Interval>
e
<TimeUnit>
. Ad esempio, se imposti <Interval>
su
12 per un <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ù punti del proxy API. Ad esempio, puoi collocarlo nel PreFlow del proxy in modo che venga eseguito su ogni richiesta. In alternativa, puoi inserirlo su più flussi nel proxy API. Se utilizzi questo criterio in più punti del proxy, viene mantenuto un singolo contatore aggiornato da tutte le istanze del criterio.
In alternativa, puoi definire più criteri per le quote nel proxy API. Ogni criterio di quota
gestisce il proprio contatore, in base all'attributo name
del criterio.
Impostare l'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 un'intestazione contenente
il 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
<Identifier>
elemento utilizza la variabile di flusso client_id
di una
norma VerifyAPIKey denominata verify-api-key
:
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
Ogni valore client_id
univoco ora definisce il proprio contatore nel criterio
di 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>
Puoi impostare i limiti di quota in modo dinamico utilizzando un conteggio della quota basato sulla classe. In questo esempio,
il limite di quota è determinato dal valore dell'intestazione developer_segment
passata con ogni richiesta. La variabile può avere un valore platinum
o silver
. Se l'intestazione ha un valore non valido, il criterio restituisce un errore di violazione della quota.
Elemento <Quota>
Di seguito sono riportati gli attributi e gli elementi secondari di <Quota>
. Tieni presente che alcune combinazioni di elementi sono mutuamente esclusive o non obbligatorie. Consulta i sample per un 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 delle variabili provengono dalle impostazioni di quota del prodotto API a cui è associata la chiave, come descritto in Ottenere le 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 | Predefinito | Presenza |
---|---|---|---|
tipo |
Imposta il tipo di criterio di quota, che determina quando e come il contatore delle quote controlla l'utilizzo delle quote e come viene reimpostato. Se non imposti I valori validi includono:
Per una descrizione completa di ciascun tipo, consulta Tipi di criteri di quota. |
N/D | Facoltativo |
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta su Imposta su |
falso | Facoltativo |
enabled |
Imposta su Imposta |
true | Facoltativo |
async |
Questo attributo è stato ritirato. |
falso | Ritirato |
Elemento <DisplayName>
Da utilizzare insieme 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/D Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
<Allow>
Specifica il limite di conteggio per la quota. Se il contatore per il criterio raggiunge questo valore di limite, le chiamate successive vengono rifiutate fino al ripristino del contatore.
Può anche contenere un elemento <Class>
che condiziona l'elemento <Allow>
in base a una variabile di flusso.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Tipo 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
che countRef
, countRef
ha la priorità. Se countRef
non viene risolto in fase di esecuzione, 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 tabella seguente elenca gli attributi di <Allow>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
conteggio |
Da utilizzare per specificare un conteggio dei messaggi per la quota. Ad esempio, un valore dell'attributo |
2000 | Facoltativo |
countRef |
Da utilizzare per specificare una variabile di flusso contenente il conteggio dei messaggi per una quota.
|
nessuno | Facoltativo |
<Class>
Consente di condizionare il valore
dell'elemento <Allow>
in base al valore di una variabile di flusso. Per ogni tag secondario <Allow>
diverso di <Class>
, il criterio gestisce un contatore diverso.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Tipo complesso |
Elemento principale |
<Allow>
|
Elementi secondari |
<Allow> (elemento 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>
per determinare il conteggio consentito del criterio. Apigee associa 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
di peak_time
o off_peak_time
. Se il parametro query contiene un valore non valido, il criterio restituisce un errore di violazione della quota.
La tabella seguente elenca gli attributi di <Class>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref | Da utilizzare per specificare una variabile di flusso contenente la classe di quota per una quota. | nessuno | Obbligatorio |
<Allow>
(elemento secondario di <Class>
)
Specifica il limite per un contatore delle quote
definito dall'elemento <Class>
. Per ogni
tag figlio <Allow>
diverso di <Class>
, il
criterio gestisce un contatore diverso.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Tipo complesso |
Elemento principale |
<Class>
|
Elementi secondari |
Nessuno |
Ad esempio:
<Allow> <Class ref="request.queryparam.time_variable"> <Allow count="5000"/> <Allow count="1000"/> </Class> </Allow>
In questo esempio, il criterio di quota gestisce due contatori di quota denominati
peak_time
e off_peak_time
. La scelta dipende dal parametro di query passato, come mostrato nell'esempio <Class>
.
La tabella seguente elenca gli attributi di <Allow>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
classe | Definisce il nome del contatore della quota. | nessuno | Obbligatorio |
conteggio | 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/a |
Obbligatorio? | Obbligatorio |
Tipo | Numero intero |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Da utilizzare per specificare un numero intero (ad es. 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 un <TimeUnit>
di hour
significa che la quota verrà calcolata nell'arco di 24 ore.
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
La tabella seguente elenca gli attributi di <Interval>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref |
Da utilizzare per specificare una variabile di flusso contenente l'intervallo per una quota. |
nessuno | Facoltativo |
<TimeUnit>
Specifica l'unità di tempo applicabile alla quota.
Valore predefinito | n/a |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Seleziona tra minute
, hour
, day
,
week
, month
o year
.
Ad esempio, un Interval
di 24
con un TimeUnit
di hour
indica che la quota verrà calcolata nell'arco di 24 ore.
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Valore predefinito: | nessuno |
Presenza: | Obbligatorio |
Tipo: | Stringa |
La tabella seguente elenca gli attributi di <TimeUnit>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref | 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 viene risolto in fase di runtime, viene utilizzato il valore dell'intervallo. |
nessuno | Facoltativo |
<StartTime>
Quando type
è impostato su calendar
, specifica la data
e l'ora in cui inizia il conteggio del contatore delle quote, indipendentemente dal fatto che siano state ricevute richieste
da app.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo (obbligatorio quando type è impostato su calendar ) |
Tipo | Stringa nel formato data e ora ISO 8601 |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Devi fornire un <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 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 | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Imposta su true
per specificare che il criterio deve mantenere un contatore centralizzato e sincronizzarlo continuamente su tutti i nodi. I nodi possono essere distribuiti in zone di disponibilità e/o regioni.
Se utilizzi il valore predefinito false
, potresti superare la quota perché il conteggio per ogni 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 un contatore delle quote distribuite in modo sincrono.
Valore predefinito | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Imposta su true
per aggiornare in modo sincrono un contatore delle quote distribuite. Ciò significa che gli aggiornamenti dei contatori vengono eseguiti contemporaneamente alla verifica della quota in una richiesta all'API. Imposta su true
se è essenziale non consentire chiamate API superiori alla quota.
Impostato su false
per aggiornare il contatore delle quote in modo asincrono. Ciò significa che è possibile che alcune chiamate API che superano la quota vengano eseguite, a seconda di quando viene aggiornato in modo asincrono il contatore delle quote nel repository centrale. Tuttavia, non dovrai affrontare
i potenziali impatti sulle prestazioni associati 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 del criterio <Synchronous>
non è presente o è presente e impostato su false
. Apigee ignora questo elemento quando <Synchronous>
è impostato su
true
.
Valore predefinito | n/a |
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 si sincronizza ogni M messaggi, dove M è il valore specificato nell'elemento, o ogni 10 secondi, a seconda dell'evento che si verifica per primo. - Quando sono presenti entrambi gli elementi, la quota si sincronizza ogni M messaggi o ogni N secondi, a seconda dell'evento che si verifica per primo.
- Quando
<AsynchronousConfiguration>
non è presente o non è presente nessuno degli elementi secondari, 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 | Numero intero |
Elemento principale |
<AsynchronousConfiguration>
|
Elementi secondari |
Nessuno |
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
L'intervallo di sincronizzazione deve essere >= 10 secondi, come descritto in Limiti.
<SyncMessageCount>
Specifica il numero di richieste da elaborare prima di sincronizzare il contatore delle quote.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Numero intero |
Elemento principale |
<AsynchronousConfiguration>
|
Elementi secondari |
Nessuno |
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
Se utilizzi la configurazione in questo esempio, su ogni nodo il conteggio della quota 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 univoci in base a una variabile di flusso.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
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
criterio VerifyAPIKey, 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 a ogni app specifica. La configurazione per quest'ultima è la seguente:
<Identifier ref="client_id"/>
Puoi fare riferimento a una variabile personalizzata che potresti impostare con il criterio Assegna messaggio o il criterio JavaScript oppure a una variabile impostata in modo implicito, come quelle impostate dal criterio VerificaAPIKey o dal criterio VerificaJWT. Per saperne di più sulle variabili, consulta la sezione Utilizzare le variabili di flusso e per un elenco di variabili ben note definite da Apigee, consulta il riferimento alle variabili di flusso.
Se non utilizzi questo elemento, il criterio assegna tutti i conteggi delle chiamate a un unico contatore per il criterio per le quote specifico.
Questo elemento è trattato anche in Come funziona il criterio di quota quando non viene specificato alcun identificatore?
La tabella seguente descrive gli attributi di <Identifier>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref |
Specifica una variabile di flusso che identifica il contatore da utilizzare per la richiesta. La variabile può fare riferimento a un'intestazione HTTP, a un parametro di query, a un parametro di un modulo o a un elemento dei contenuti del messaggio oppure a un altro valore per identificare la modalità di assegnazione dei conteggi delle chiamate.
|
N/D | Facoltativo |
<MessageWeight>
Specifica il costo assegnato a ogni messaggio ai fini della quota. Utilizza questo elemento per aumentare l'impatto dei messaggi di richiesta che, ad esempio, consumano più risorse di calcolo rispetto ad altri.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Numero intero |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Ad esempio, vuoi conteggiare i messaggi POST
come se avessero un costo doppio rispetto ai messaggi GET
. Pertanto, 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 consente 5 richieste POST
in qualsiasi intervallo di 10 minuti. Eventuali richieste aggiuntive,
POST
o GET
, prima del ripristino del contatore vengono rifiutate.
Un valore che rappresenta <MessageWeight>
deve essere specificato da una variabile
del flusso e può essere estratto dalle intestazioni HTTP, parametri di ricerca, da un payload
della richiesta XML o JSON o da qualsiasi altra variabile del flusso. Ad esempio, puoi impostarlo in un'intestazione denominata
weight
:
<MessageWeight ref="message_weight"/>
<UseQuotaConfigInAPIProduct>
Definisce le impostazioni di quota per un prodotto API, ad esempio le unità di tempo, l'intervallo e il valore massimo consentito.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Tipo complesso |
Elemento principale |
<Quota>
|
Elementi secondari |
<DefaultConfig> |
Se aggiungi l'elemento <UseQuotaConfigInAPIProduct>
al criterio Quota, Apigee ignora 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 criterio VerifyAPIKey o a un'operazione del criterio ValidateToken
del criterio OAuthv2 nel flusso.
La tabella seguente descrive gli attributi di <UseQuotaConfigInAPIProduct>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
stepName | Identifica il nome del criterio di autenticazione nel flusso. Il target può essere un criterio VerifyAPIKey o un criterio OAuthv2. | N/D | Obbligatorio |
Per ulteriori informazioni, consulta le seguenti risorse:
<DefaultConfig>
Contiene i valori predefiniti per la quota di un prodotto API. Quando definisci un <DefaultConfig>
,
tutti e tre gli elementi secondari sono obbligatori.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Tipo complesso |
Elemento principale |
<UseQuotaConfigInAPIProduct>
|
Elementi secondari |
<Allow> <Interval> <TimeUnit> |
È possibile definire questi valori sia nell'operazione del prodotto API (con l'interfaccia utente o l'API API Products) sia nel criterio di quota. Tuttavia, se lo fai, le impostazioni del prodotto API hanno la precedenza e quelle del criterio di quota 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 delle quote sottostante. Se questo elemento
è presente, devono essere presenti anche gli elementi <EnforceOnly>
o
<CountOnly>
.
Per ulteriori informazioni e esempi, consulta Configurare i contatori delle quote condivise.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
<CountOnly>
Inserisci un criterio di quota con questo elemento impostato su true
in un passaggio condizionale nel flusso di risposta di 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 e esempi, consulta Configurare i contatori delle quote condivise.
Valore predefinito | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
<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 e esempi, consulta Configurare i contatori delle quote condivise.
Valore predefinito | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<Quota>
|
Elementi secondari |
Nessuno |
Variabili di flusso
Le seguenti variabili di flusso predefinite vengono completate automaticamente quando viene eseguito un criterio di quota. Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso.
Variabili | Tipo | Autorizzazioni | Descrizione |
---|---|---|---|
ratelimit.{policy_name}.allowed.count | Lungo | Sola lettura | Restituisce il conteggio della quota consentita. |
ratelimit.{policy_name}.used.count | Lungo | Sola lettura | Restituisce la quota corrente utilizzata all'interno di un intervallo di quota. |
ratelimit.{policy_name}.available.count | Lungo | Sola lettura | Restituisce il numero di quote disponibili 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 l'ora UTC (in millisecondi), che determina la scadenza della quota e l'inizio del nuovo intervallo di quota. Quando il tipo del criterio di quota è |
ratelimit.{policy_name}.identifier | Stringa | Sola lettura | Restituisce il riferimento all'identificatore (client) associato al criterio |
ratelimit.{policy_name}.class | Stringa | Sola lettura | Restituisce la classe associata all'identificatore client |
ratelimit.{policy_name}.class.allowed.count | Lungo | Sola lettura | Restituisce il numero di quote consentite definito nella classe |
ratelimit.{policy_name}.class.used.count | Lungo | Sola lettura | Restituisce la quota utilizzata all'interno di un corso |
ratelimit.{policy_name}.class.available.count | Lungo | Sola lettura | Restituisce il numero di quote disponibili nel corso |
ratelimit.{policy_name}.class.exceed.count | Lungo | Sola lettura | Restituisce il conteggio delle richieste che superano il limite nel corso nell'intervallo di quota corrente |
ratelimit.{policy_name}.class.total.exceed.count | Lungo | Sola lettura | Restituisce il conteggio totale delle richieste che superano il limite nel corso in tutti
gli intervalli di quota, quindi è 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 positivo o meno (true o false). |
Messaggi di errore
Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice guasto | Stato HTTP | Causa | Correggi |
---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 |
Si verifica se l'elemento <Interval> non è definito nel criterio Quota . Questo elemento
è obbligatorio e viene utilizzato per specificare l'intervallo di tempo applicabile alla quota. L'intervallo di tempo
può essere in minuti, ore, giorni, settimane o mesi, come definito con l'elemento <TimeUnit> . |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 |
Si verifica se l'elemento <TimeUnit> non è definito nel criterio Quota . Questo elemento è obbligatorio e viene utilizzato per specificare l'unità di tempo applicabile alla quota. L'intervallo di tempo può essere in minuti, ore, giorni, settimane o mesi. |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
Si verifica se il valore dell'elemento <MessageWeight> specificato tramite una variabile di flusso
non è valido (un valore non intero). |
build |
policies.ratelimit.QuotaViolation |
500 |
È stato superato il limite di quota. | N/D |
Errori di deployment
Nome dell'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 va a buon fine.
|
build |
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 .
|
build |
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 quote supportati sono default , calendar , flexi e rollingwindow .
|
build |
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 data e ora ISO 8601. Ad esempio, se l'ora specificata nell'elemento <StartTime> è 7-16-2017 12:00:00 , il deployment del proxy API non va a buon fine.
|
build |
StartTimeNotSupported |
Se viene specificato l'elemento <StartTime> di cui il 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.
|
build |
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. |
build |
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 va a buon fine. |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
Se il valore dell'elemento <AsynchronousConfiguration> è impostato su true in un criterio Quota , che ha anche una configurazione asincrona definita utilizzando l'elemento <AsynchronousConfiguration> , il deployment del proxy API non va a buon fine. |
build |
Variabili di errore
Queste variabili vengono impostate quando questo criterio attiva un errore. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'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>
Schemi
Argomenti correlati
Confronto tra i criteri Quota e SpikeArrest