Criteri per le quote

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:

Samples

Questi esempi di codice dei criteri illustrano come iniziare e terminare i periodi di quota mediante:

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

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.

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

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>

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.

Attributi

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.

Attributi

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.

Attributi

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>

Attributi

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>

Attributi

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>

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>

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>

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>

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.

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.

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

Attributi

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

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.

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.

Errori di deployment

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.

Esempio di risposta di errore

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

Esempio di regola di errore

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Schema

Argomenti correlati

Criterio di ResetQuota

Norme di SpikeArrest

Confronto tra i criteri di quota, arresto dei picchi e limite di frequenza in parallelo