Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
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 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 la quota per proteggerti dai picchi di traffico complessivi. A questo scopo, utilizza il criterio Spike Arrest. Consulta le norme relative al servizio di arresto di Spike.
Video
Questi video presentano la gestione delle quote con i criteri per le quote:
Introduzione (nuovo bordo)
Introduzione (perimetro classico)
Quota dinamica
Distribuito e sincrono
Peso del messaggio
Calendario
Finestra temporale continua
Flex
Quota condizionale
Variabili di flusso
Gestione degli errori
Samples
Questi esempi di codice dei criteri illustrano come iniziare e terminare i periodi di quota mediante:
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 consentono di configurare un singolo criterio per le quote che applica impostazioni delle quote diverse in base alle informazioni passate al criterio per le quote. Un altro termine per le impostazioni delle quote in questo contesto è "piano di servizio". La quota dinamica controlla il "piano di servizio" delle app e applica quindi le impostazioni.
Nota: se specifichi sia un valore sia un riferimento per un elemento, il riferimento ottiene la priorità. Se il riferimento non si risolve in fase di runtime, viene utilizzato il valore.
Ad esempio, quando crei un prodotto API, puoi facoltativamente impostare il limite di quota consentito, l'unità di tempo e l'intervallo. Tuttavia, l'impostazione di questo valore nel prodotto API non ne impone 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 VerificationAPIKey denominato verify-api-key
per convalidare la chiave API trasmessa in una richiesta. Il criterio per le quote accede quindi alle variabili di flusso dal criterio VerificationAPIKey per leggere i valori della quota impostati per il prodotto API. Per ulteriori informazioni sulle variabili di flusso VerificationAPIKey, consulta l'articolo Verificare il criterio della chiave API.
Un'altra opzione consiste nell'impostare attributi personalizzati su singoli sviluppatori o app e poi leggere questi valori nel criterio per le quote. Ad esempio, vuoi impostare valori di quota diversi per sviluppatore. In questo caso, devi impostare sullo sviluppatore attributi personalizzati contenenti il limite, l'unità di tempo e l'intervallo. Successivamente, farai 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 per lo sviluppatore.
Puoi utilizzare qualsiasi variabile per impostare i parametri del criterio per le quote. Queste variabili possono provenire da:
- Variabili di flusso
- Proprietà sul prodotto, sull'app o sullo sviluppatore API
- Una mappa chiave-valore (KVM)
- Un'intestazione, un parametro di ricerca, un parametro del modulo ecc.
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 il criterio e il proxy in questione.
Ora di inizio
<Quota name="QuotaPolicy" type="calendar"> <StartTime>2017-02-18 10:30:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
Per una quota con type
impostata 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
, Edge genera un errore.
Il contatore di quota 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 2017 e viene aggiornato ogni 5 ore. Pertanto, il prossimo aggiornamento sarà alle 15:30 GMT del 18 febbraio 2017.
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 dai criteri 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 di quota attuale a un'app o per altri motivi.
Poiché l'accesso alle variabili di flusso per il criterio si basa sull'attributo
name
del criterio, per il criterio sopra denominato QuotaPolicy
accedi alle relative 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 azzerato il contatore.
Esistono molte altre variabili di flusso, come descritto di seguito.
Ad esempio, puoi utilizzare il seguente criterio di AssegnaMessage per restituire i valori delle variabili di flusso quota come intestazioni di risposta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars"> <AssignTo createNew="false" type="response"/> <Set> <Headers> <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header> <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header> <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
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 10.000 vengono rifiutate.
Ad esempio, se il contatore inizia da 2017-07-08 07:00:00
, viene reimpostato su 0 alle ore 2017-07-08 08:00:00
(1 ora dall'ora di inizio). Se il primo messaggio viene ricevuto
alle ore 2017-07-08 07:35:28
e il numero di messaggi raggiunge 10.000
prima del giorno 2017-07-08 08:00:00
, le chiamate oltre questo numero vengono rifiutate finché
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 un <TimeUnit>
d'ora, il contatore viene reimpostato ogni dodici ore.
Puoi impostare <TimeUnit>
su minuto, ora, giorno, settimana o mese.
Puoi fare riferimento a queste norme in più punti nel proxy API. Ad esempio, puoi posizionarlo nel preflusso del proxy 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 nel proxy, verrà conservato un unico contatore che viene aggiornato da tutte le istanze del criterio.
In alternativa, puoi definire più criteri per le quote nel proxy API. Ogni criterio per le quote mantiene il proprio contatore, in base all'attributo name
del criterio.
Imposta identificatore
<Quota name="QuotaPolicy" type="calendar"> <Identifier ref="request.header.clientId"/> <StartTime>2017-02-18 10:00:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
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 tuo proxy, l'app client passa un'intestazione contenente clientID
, come mostrato nell'esempio precedente.
Puoi specificare qualsiasi variabile di flusso per l'attributo <Identifier>
. Ad esempio, potresti specificare che un parametro di query denominato id
contiene l'identificatore univoco:
<Identifier ref="request.queryparam.id"/>
Se utilizzi il criterio VerificationAPIKey per convalidare la chiave API o i criteri OAuthV2 con i token OAuth, puoi utilizzare le informazioni nella chiave o nel token API per definire singoli contatori per lo stesso criterio per le quote. Ad esempio, il seguente tag <Identifier>
utilizza la variabile di flusso client_id
di un criterio di VerificationAPIKey denominato verify-api-key
:
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
Ogni valore client_id
univoco ora definisce il proprio contatore nei criteri 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 sulla classe. In questo esempio, il limite di quota è determinato dal valore dell'intestazione developer_segment
trasmesso con ogni richiesta. Questa variabile può avere un valore pari a platinum
o silver
. Se l'intestazione contiene un valore non valido, il criterio restituisce un errore di violazione della quota.
Informazioni sui criteri per le quote
Una quota è un'allocazione dei messaggi di richiesta che un proxy API può gestire in un determinato periodo di tempo, ad esempio minuto, ora, giorno, settimana o mese. Il criterio conserva dei 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 intervallo di tempo. Utilizzando i criteri per le quote, puoi, ad esempio, limitare le app a 1 richiesta al minuto o a 10.000 richieste al mese.
Ad esempio, se una quota è definita come 10.000 messaggi al mese, la limitazione di frequenza inizia dopo il 10.000° messaggio. Non importa se sono stati conteggiati 10.000 messaggi il primo giorno o l'ultimo giorno di quel periodo; non è consentita alcuna area per richieste aggiuntive fino a quando il contatore delle quote non viene reimpostato automaticamente al termine dell'intervallo di tempo specificato o finché la quota non viene reimpostata esplicitamente tramite il criterio di reimpostazione della quota.
Una variante della quota chiamata SpikeArrest previene picchi (o burst) di traffico che possono essere causati da un improvviso aumento dell'utilizzo, da client con bug o da attacchi dannosi. Per maggiori informazioni su SpikeArrest, consulta le norme relative all'arresto di Spike.
Le quote si applicano ai singoli proxy API e non sono distribuite tra i proxy API. Ad esempio, se hai tre proxy API in un prodotto API, un'unica quota non viene condivisa tra tutti e tre, anche se tutti e tre utilizzano la stessa configurazione dei criteri delle quote.
Tipi di criteri per le quote
Il criterio per le quote supporta diversi tipi di criteri: predefiniti, calendar
,
flexi
e rollingwindow
. Ogni tipo definisce quando viene avviato e quando il contatore delle quote viene reimpostato, come illustrato nella tabella seguente:
Unità di tempo | Reimpostazione predefinita (o null) | reimpostazione calendario | ripristino flexi |
---|---|---|---|
minuto | Inizio del minuto successivo | Un minuto dopo <StartTime> |
Un minuto dopo la prima richiesta |
ora | Parte superiore 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) 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 per le finestre temporali continue funzionano impostando le dimensioni di una "finestra", ad esempio una finestra di un'ora o di un giorno. Quando arriva una nuova richiesta, il criterio determina se la quota è stata superata nella "finestra" di tempo passata.
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 l'intervallo di due ore precedente, ovvero il numero di richieste a partire dalle 14:45. Se il limite di quota non è stato superato in questo periodo di due ore, la richiesta è consentita.
Un minuto dopo, alle 16:46, arriva un'altra richiesta. Ora il criterio calcola il conteggio della quota 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 di quota
Per impostazione predefinita, un criterio per le quote mantiene un singolo contatore, indipendentemente dal numero di volte in cui viene fatto riferimento in un proxy API. Il nome del contatore di quote 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 posizioni su più flussi (flusso A, B e C) nel proxy API. Anche se viene
utilizzato in più flussi, mantiene un singolo contatore che viene aggiornato da tutte le istanze del
criterio:
- Il flusso A viene eseguito -> MyQuotaPolicy viene eseguito e il rispettivo contatore = 1
- Viene eseguito il flusso B -> MyQuotaPolicy viene eseguito e il rispettivo contatore = 2
- Il flusso A viene eseguito -> MyQuotaPolicy viene eseguito e il rispettivo contatore = 3
- Il flusso C viene eseguito -> MyQuotaPolicy viene eseguito e il rispettivo contatore = 4
- Il flusso A viene eseguito -> MyQuotaPolicy viene eseguito e il rispettivo contatore = 5
La richiesta successiva a uno dei tre flussi viene rifiutata perché il contatore di quota ha raggiunto il limite.
L'utilizzo dello stesso criterio per le quote in più punti in un flusso proxy API, il che può causare involontariamente un'esaurimento della quota più rapida del previsto, è un anti-pattern descritto nell'articolo The Book of Apigee Edge Anti-pattern.
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, in base all'attributo name
del criterio.
In alternativa, utilizza gli elementi <Class>
o <Identifier>
nei criteri per le quote per definire più contatori univoci in un singolo criterio. Utilizzando questi
elementi, un singolo criterio può gestire diversi contatori in base all'app che effettua la richiesta,
allo sviluppatore dell'app che ha effettuato la richiesta, a un ID client o 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 del tempo della quota segue la notazione della data dello standard internazionale definito nello standard internazionale ISO 8601.
Le date vengono definite come anno, mese e giorno nel seguente formato: YYYY-MM-DD
.
Ad esempio, 2015-02-04
rappresenta il 4 febbraio 2015.
L'ora del giorno viene definita come ore, minuti e secondi nel seguente formato:
hours:minutes:seconds
. Ad esempio, 23:59:59
rappresenta l'ora un secondo prima di mezzanotte.
Tieni presente che sono disponibili due notazioni, 00:00:00
e 24:00:00
, per distinguere le due mezzenotte che possono essere associate a una data. Pertanto, 2015-02-04
24:00:00
corrisponde alla stessa data e ora di 2015-02-05 00:00:00
. La seconda opzione è in genere la soluzione preferita.
Recupero delle impostazioni delle quote dalla configurazione del prodotto API
Puoi impostare limiti di quota nelle configurazioni dei prodotti API. Questi limiti non applicano automaticamente la quota. Puoi invece fare riferimento alle impostazioni delle quote per i prodotti in un criterio per le quote. Ecco alcuni vantaggi dell'impostazione di una quota sul prodotto a cui fare riferimento i criteri per le quote:
- 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 su un prodotto API e i criteri per le quote che fanno riferimento al valore avranno automaticamente valori di quota aggiornati.
Per ulteriori informazioni sull'utilizzo delle impostazioni delle quote da un prodotto API, vedi l'esempio "Quota dinamica" riportato sopra..
Per informazioni sulla configurazione di prodotti basati su API con limiti di quota, consulta Creare prodotti basati su API.
Riferimento elemento
Di seguito sono riportati gli elementi e gli attributi che puoi configurare su questo criterio. Tieni presente che alcune combinazioni di elementi si escludono a vicenda o non sono obbligatorie. Guarda gli esempi per un utilizzo specifico. Le
variabili verifyapikey.VerifyAPIKey.apiproduct.*
riportate di seguito sono disponibili per impostazione predefinita quando
viene utilizzato un criterio di verifica della chiave API denominato "VerifyAPIKey" per verificare la chiave API dell'app nella richiesta.
I valori della variabile derivano dalle impostazioni delle quote nel prodotto API a cui è associata la chiave, come descritto in Recupero delle impostazioni delle quote dalla configurazione del prodotto API.
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar"> <DisplayName>Quota 3</DisplayName> <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> <Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow> <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit> <StartTime>2017-7-16 12:00:00</StartTime> <Distributed>false</Distributed> <Synchronous>false</ Synchronous> <AsynchronousConfiguration> <SyncIntervalInSeconds>20</ SyncIntervalInSeconds> <SyncMessageCount>5</ SyncMessageCount> </AsynchronousConfiguration> <Identifier/> <MessageWeight/> </Quota>
Attributi <Quota>
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
I seguenti attributi sono specifici di questa norma.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
digita |
Da utilizzare per determinare quando e come il contatore di quote controlla l'utilizzo della quota. Per saperne di più, consulta Tipi di criteri per le quote. Se ometti un valore I valori validi sono:
|
calendar | 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 Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
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 |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Allow>
Specifica il limite di conteggio per la quota. Se il contatore del criterio raggiunge questo valore limite, le chiamate successive vengono rifiutate fino alla reimpostazione del contatore.
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 si risolve in fase di runtime, viene utilizzato il valore di
count
.
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | Numero intero |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
conteggio |
Consente di 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 |
Elemento <Allow>/<Class>
L'elemento <Class>
consente di condizionalizzare 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.
Per utilizzare l'elemento <Class>
, specifica una variabile di flusso tramite l'attributo ref
nel tag <Class>
. Quindi, Edge utilizza il valore della variabile di flusso per selezionare uno dei tag secondari <Allow>
per determinare il conteggio consentito del criterio. Edge abbina il valore della variabile di flusso all'attributo class
del tag <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 di quota corrente è determinato dal valore del
parametro di query time_variable
trasmesso 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.
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif |
Da utilizzare per specificare una variabile di flusso contenente la classe di una quota. |
Nessuno | Obbligatorio |
Elemento <Allow>/<Class>/<Allow>
L'elemento <Allow>
specifica il limite per un contatore di quote
definito dall'elemento <Class>
. Per ogni diverso tag secondario <Allow>
di <Class>
, il criterio mantiene un contatore diverso.
Ad esempio:
<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 criterio per le quote mantiene due contatori di quota denominati
peak_time
e off_peak_time
.
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
classe |
Definisce il nome del contatore di quota. |
Nessuno | Obbligatorio |
conteggio | Specifica il limite di quota per il contatore. | Nessuno | Obbligatorio |
Elemento <Intervalli>
Consente di specificare un numero intero (ad esempio 1, 2, 5, 60 e così via) che verrà accoppiato al valore TimeUnit
specificato (minuto, ora, giorno, settimana o mese) per determinare un periodo di tempo durante il quale Edge calcola l'utilizzo della quota.
Ad esempio, Interval
pari a 24
con
TimeUnit
pari a hour
significa che la quota verrà calcolata
nell'arco di 24 ore.
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
Predefinito: | Nessuno |
Presenza: | Obbligatorio |
Tipo: | Numero intero |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif |
Consente di specificare una variabile di flusso contenente l'intervallo per una quota. |
Nessuno | Facoltativo |
Elemento <TimeUnit>
Da utilizzare per specificare l'unità di tempo applicabile alla quota.
Ad esempio, Interval
pari a 24
con
TimeUnit
pari a hour
significa che la quota verrà calcolata
nell'arco di 24 ore.
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Predefinito: | Nessuno |
Presenza: | Obbligatorio |
Tipo: |
Stringa. Seleziona un'opzione tra |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif | Consente di specificare 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. |
Nessuno | Facoltativo |
Elemento <StartTime>
Quando type
è impostato su calendar,
, consente di specificare la data e l'ora in cui il contatore di quote inizierà a conteggiare, indipendentemente dal fatto che siano state ricevute richieste da app.
Devi fornire un valore StartTime
esplicito quando type
è impostato esplicitamente su calendar,
. Non puoi utilizzare un riferimento a una variabile di flusso. Se specifichi un valore StartTime
quando non è impostato alcun valore type
, viene visualizzato un errore.
Ad esempio:
<StartTime>2017-7-16 12:00:00</StartTime>
Predefinito: | Nessuno |
Presenza: | Obbligatorio quando type è impostato su calendar . |
Tipo: |
Stringa nel formato di data e ora ISO 8601. |
Elemento <Distributed>
Un'installazione di Edge può utilizzare uno o più processori di messaggi per elaborare le richieste. Imposta questo elemento su true
per specificare che il criterio deve mantenere un contatore centrale e sincronizzarlo continuamente su tutti i processori di messaggi. I processori dei messaggi possono trovarsi in zone e/o regioni di disponibilità diverse.
Se utilizzi il valore predefinito di false
, potresti superare la quota perché il conteggio per ciascun processore di messaggi non è condiviso:
<Distributed>true</Distributed>
Per garantire che i contatori siano sincronizzati e aggiornati su ogni richiesta, imposta
<Distributed>
e <Synchronous>
su true:
<Distributed>true</Distributed> <Synchronous>true</Synchronous>
Predefinito: | false |
Presenza: | Facoltativo |
Tipo: | Booleano |
Elemento <Synchronous>
Imposta su true
per aggiornare in modo sincrono un contatore delle quote distribuite. Ciò significa che l'aggiornamento del contatore viene eseguito contemporaneamente al controllo della quota su una richiesta all'API. Imposta su true
se è essenziale non consentire chiamate API oltre la quota.
Imposta su false
per aggiornare il contatore di quota in modo asincrono. Ciò significa che è possibile che vengano effettuate alcune chiamate API che superano la quota, a seconda di quando il contatore di quota 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 è 10 secondi. Utilizza
l'elemento AsynchronousConfiguration
per configurare questo comportamento asincrono.
<Synchronous>false</Synchronous>
Predefinito: | false |
Presenza: | Facoltativo |
Tipo: | Booleano |
Elemento <AsyncConfiguration>
Consente di configurare l'intervallo di sincronizzazione tra i contatori delle quote distribuite quando l'elemento di configurazione dei criteri <Synchronous>
non è presente o è presente ed è impostato su false
.
Puoi eseguire la sincronizzazione dopo un periodo di tempo o un conteggio di messaggi utilizzando gli elementi secondari SyncIntervalInSeconds
o SyncMessageCount
.
Si escludono a vicenda. Ad esempio:
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
o
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
Predefinito: | SyncIntervalliInsecondi = 10 secondi |
Presenza: | Facoltativo; ignorato quando <Synchronous> è impostato su
true . |
Tipo: |
Complesso |
Elemento <AsyncConfiguration>/<Sync5InSECONDS>
Utilizza questa impostazione per eseguire l'override del comportamento predefinito in cui gli aggiornamenti asincroni vengono eseguiti dopo un intervallo di 10 secondi.
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
L'intervallo di sincronizzazione deve essere maggiore o uguale a 10 secondi, come descritto nell'argomento Limiti.
Predefinito: | 10 |
Presenza: | Facoltativo |
Tipo: |
Numero intero |
Elemento <AsyncConfiguration>/<SyncMessageCount>
Specifica il numero di richieste in tutti i processori di messaggi Apigee tra gli aggiornamenti della quota.
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
Questo esempio specifica che il conteggio della quota viene aggiornato ogni 5 richieste su ciascun processore di messaggi Apigee Edge.
Predefinito: | n/d |
Presenza: | Facoltativo |
Tipo: |
Numero intero |
Elemento <Identifier>
Utilizza l'elemento <Identifier>
per configurare il criterio in modo da creare contatori univoci basati su una variabile di flusso.
Se non utilizzi questo elemento, il criterio utilizza un singolo contatore che viene applicato alla quota.
Questo elemento è discusso anche nel seguente post della community di Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.
<Identifier ref="verifyapikey.verify-api-key.client_id"/>
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: |
Stringa |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif |
Specifica una variabile di flusso che identifica il contatore da utilizzare per la richiesta. L'identificatore può essere un'intestazione HTTP, un parametro di ricerca, un parametro di modulo o un contenuto di messaggio univoco per ogni app, utente dell'app, sviluppatore di app, prodotto API o altra caratteristica. Il In alcuni casi, le impostazioni della quota devono essere recuperate se non è disponibile |
N/A | Facoltativo |
Elemento <MessageWeight>
Da utilizzare per specificare il peso assegnato a ciascun messaggio. Utilizza la ponderazione dei messaggi per aumentare l'impatto dei messaggi di richiesta che, ad esempio, consumano più risorse di calcolo rispetto ad altri.
Ad esempio, potresti voler conteggiare i messaggi POST come se fossero due volte più "pesanti" o costosi, rispetto ai messaggi GET. Pertanto, imposti MessageWeight
su 2 per un POST e 1 per un 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 MessageWeight
per le richieste POST è 2
, allora la quota consentirà 5 richieste POST in un 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 query, un payload di richiesta XML o JSON o qualsiasi altra variabile di flusso. Ad esempio, lo imposti in un'intestazione denominata
weight
:
<MessageWeight ref="message_weight"/>
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: |
Numero intero |
Variabili di flusso
Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando viene eseguito un criterio per le quote. Per ulteriori informazioni sulle variabili di flusso, consulta le informazioni di riferimento sulle variabili.
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 entro 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 l'ora UTC in millisecondi che determina quando scade la quota e inizia il nuovo intervallo di quota. Quando il tipo di criterio per le quote è |
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 conteggio della quota 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 della quota disponibile nella classe |
ratelimit.{policy_name}.class.exceed.count | Lungo | Sola lettura | Restituisce il conteggio delle richieste che supera il limite nella 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 (true o false). |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge 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 nei criteri per le quote. 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> . |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | Si verifica se l'elemento <TimeUnit> non è definito nei criteri per le quote. 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. |
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 | 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.
|
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 quota 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 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.
|
build |
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.
|
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 per le quote è 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 per le quote, in cui è definita anche una configurazione asincrona mediante l'elemento <AsynchronousConfiguration> , il deployment del proxy API non riesce. |
build |
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
Confronto tra i criteri di quota, arresto dei picchi e limite di frequenza in parallelo