Criteri per le quote

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

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 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 la quota per proteggerti dagli picchi di traffico complessivi. A questo scopo, utilizza il criterio SpikeArrest. Consulta le norme relative a Spike Arrest.

Video

Questi video illustrano la gestione delle quote con le norme relative alle quote:

Esempi

Questi esempi di codice delle norme mostrano come iniziare e terminare i periodi di quota in base a:

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

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

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

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

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

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

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

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

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

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

Informazioni sui criteri per le quote

Una quota è un'assegnazione di messaggi di richiesta che un proxy API può gestire in un periodo di tempo, come minuti, ore, giorni, settimane o mesi. Il criterio 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.

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 di reimpostazione della quota.

Una variante di Quota chiamata SpikeArrest impedisce i picchi (o le esplosioni) di traffico che possono essere causati da un aumento improvviso dell'utilizzo, da client con bug o da attacchi dannosi. Per ulteriori informazioni su SpikeArrest, consulta la pagina Criterio SpikeArrest.

Le quote si applicano ai singoli proxy API e non vengono distribuite tra i proxy API. Ad esempio, se hai tre proxy API in un prodotto API, una singola quota non viene condivisa tra tutti e tre anche se tutti e tre utilizzano la stessa configurazione del criterio per le quote.

Tipi di criteri per le quote

Il criterio per le quote supporta diversi tipi di criteri: predefinito, calendar, flexi e rollingwindow. Ogni tipo definisce quando inizia e quando viene reimpostato il contatore delle quote, come mostrato nella tabella seguente:

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

Ad esempio, definisci un intervallo di due ore che consente 1000 richieste. Alle 16:45 arriva una nuova richiesta.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

Per impostazione predefinita, un criterio per le quote gestisce un singolo contatore, indipendentemente dal numero di volte in cui lo fai 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 del proxy API, che può causare involontariamente l'esaurimento della quota più velocemente del previsto, è un antipattern descritto nel The Book of Apigee Edge Antipatterns.

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.

In alternativa, utilizza 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, 2015-02-04 rappresenta il 4 febbraio 2015.

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, 2015-02-04 24:00:00 corrisponde alla stessa data e alla stessa ora di 2015-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 delle quote 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 saperne di più 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, vedi Creare prodotti API.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in questo criterio. Tieni presente che alcune combinazioni di elementi sono mutuamente esclusive o non obbligatorie. Consulta i sample per un utilizzo specifico. Le variabili verifyapikey.VerifyAPIKey.apiproduct.* riportate di seguito sono disponibili per impostazione predefinita quando viene utilizzato un criterio Verifica chiave API denominato "VerifyAPIKey" 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 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 questo criterio.

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

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

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 runtime, viene utilizzato il valore di count.

Attributi

Elemento <Allow>/<Class>

L'elemento <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.

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando l'attributo ref per il tag <Class>. Edge utilizza quindi il valore della variabile di flusso per selezionare uno dei tag secondari <Allow> per determinare il conteggio consentito del criterio. Edge associa 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 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.

Attributi

Elemento <Allow>/<Class>/<Allow>

L'elemento <Allow> 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.

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 di quota gestisce due contatori di quota denominati peak_time e off_peak_time.

Attributi

Elemento <Interval>

Da utilizzare per specificare un numero intero (ad es. 1, 2, 5, 60 e così via) che verrà accoppiato al 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, un Interval di 24 con un TimeUnit di hour indica che la quota verrà calcolata nell'arco di 24 ore.

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

Attributi

Elemento <TimeUnit>

Da utilizzare per specificare l'unità di tempo applicabile alla quota.

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>

Attributi

Elemento <StartTime>

Quando type è impostato su calendar,, vengono specificate la data e l'ora in cui il contatore della quota inizierà a conteggiare, indipendentemente dal fatto che siano state ricevute richieste da app.

Ad esempio:

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

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 conto centrale e sincronizzarlo continuamente in tutti i processori di messaggi. Gli elaboratori dei messaggi possono essere in zone di disponibilità e/o regioni diverse.

Se utilizzi il valore predefinito false, potresti superare la quota perché il conteggio per ogni Message Processor non è condiviso:

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

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

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

Puoi eseguire la sincronizzazione dopo un periodo di tempo o un conteggio dei 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>

Elemento <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Utilizzalo per ignorare il 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 >= 10 secondi, come descritto nell'argomento Limiti.

<AsynchronousConfiguration>/<SyncMessageCount> element

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 delle quote viene aggiornato ogni 5 richieste in ogni processore di messaggi Apigee Edge.

Elemento <Identifier>

Utilizza l'elemento <Identifier> per configurare il criterio in modo da creare contatori unici in base a una variabile di flusso.

Se non utilizzi questo elemento, il criterio utilizza un singolo contatore applicato alla quota.

Questo elemento è discusso anche nel seguente post della community 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"/>

Attributi

Elemento <MessageWeight>

Da utilizzare per specificare il peso assegnato a ogni messaggio. Utilizza il peso del messaggio per aumentare l'impatto dei messaggi di richiesta che, ad esempio, consumano più risorse di calcolo rispetto ad altri.

Ad esempio, vuoi conteggiare i messaggi POST come "pesanti" o costosi il doppio rispetto ai messaggi GET. Pertanto, imposta MessageWeight su 2 per un POST e su 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 valore MessageWeight per le richieste POST è 2, la quota consentirà 5 richieste POST in qualsiasi intervallo di 10 minuti. Eventuali richieste aggiuntive, POST o GET, prima 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, dai parametri di query, 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"/>

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono completate automaticamente quando viene eseguito un criterio di quota. Per ulteriori informazioni sulle variabili di flusso, consulta la sezione Riferimento alle variabili.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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

Criteri per ResetQuota

Criterio SpikeArrest

Confronto tra le norme relative a quota, arresto picchi e limite di frequenza simultanea