Criteri per le quote

Stai visualizzando la documentazione di Apigee Edge.
Consulta la 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 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 puoi impostarla 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 Quota per proteggerti dai picchi di traffico complessivi. Per farlo, utilizza il criterio SpikeArrest. Consulta le norme Spike Arrest.

Video

Questi video introducono 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, ad esempio minuto, ora, giorno, settimana o mese. I criteri mantengono i contatori che conteggiano il numero di richieste ricevute dal proxy API. Questa funzionalità consente ai fornitori di API di applicare limiti al numero di chiamate API effettuate dalle app in un intervallo di tempo. Utilizzando i criteri relativi alle quote puoi, ad esempio, limitare le app a una richiesta al minuto o a 10.000 richieste al mese.

Ad esempio, se una quota è definita come 10.000 messaggi al mese, la limitazione della velocità inizia dopo il 10.000° messaggio. Non importa se sono stati conteggiati 10.000 messaggi il primo o l'ultimo giorno di quel 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 in modo esplicito utilizzando le norme di reimpostazione della quota.

Una variante della quota chiamata SpikeArrest impedisce picchi (o burst) di traffico che possono essere causati da un improvviso aumento dell'utilizzo, da client con bug o da attacchi dannosi. Per ulteriori informazioni su SpikeArrest, consulta le norme 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 dei criteri per le quote.

Tipi di criteri per le quote

I criteri per le quote supportano diversi tipi di criteri: predefiniti, calendar, flexi e rollingwindow. Ogni tipo definisce quando inizia e quando viene reimpostato il contatore della quota, 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 della finestra mobile funzionano impostando le dimensioni di una "finestra" di quota, ad esempio una finestra di un'ora o di un giorno. Quando arriva una nuova richiesta, il criterio determina se la quota è stata superata nella "finestra" di tempo precedente.

Ad esempio, definisci un intervallo di due ore che consente 1000 richieste. Alle 16:45 viene ricevuta una nuova richiesta.Il criterio calcola il conteggio della quota per la finestra delle due ore precedenti, ovvero il numero di richieste 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 conteggio della quota dalle ore 14:46 per determinare se il limite è stato superato.

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

Informazioni sui contatori delle quote

Per impostazione predefinita, un criterio per le quote gestisce un unico contatore, indipendentemente dal numero di volte in cui lo fai riferimento in un proxy API. Il nome del contatore della quota si basa sull'attributo name del criterio.

Ad esempio, crei una norma relativa alle quote denominata MyQuotaPolicy con un limite di 5 richieste e la inserisci in più flussi (A, B e C) nel proxy API. Anche se viene utilizzato in più flussi, mantiene un unico contatore aggiornato da tutte le istanze del criterio:

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

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

L'utilizzo dello stesso criterio per le quote in più posizioni in un flusso proxy API, che può causare involontariamente l'esaurimento delle quote più rapidamente del previsto, è un anti-pattern descritto in 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 mantiene 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, una singola norma può mantenere contatori diversi in base all'app che effettua la richiesta, all'app sviluppatore che effettua la richiesta, a un ID client o a un altro identificatore client e altro ancora. Per ulteriori informazioni sull'utilizzo degli elementi <Class> o <Identifier>, consulta gli esempi riportati sopra.

Notazione temporale

Tutti gli orari delle quote sono impostati sul fuso orario UTC (Coordinated Universal Time).

La notazione dell'ora della quota segue la notazione internazionale della data 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 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 mezzanotte 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. Quest'ultima è di solito la notazione preferita.

Recupero delle 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 di prodotto in una norma relativa alle quote. Ecco alcuni vantaggi dell'impostazione di una quota sul prodotto a cui fare riferimento per le norme relative alle quote:

• I criteri per le quote possono utilizzare un'impostazione uniforme in tutti i proxy API del prodotto API.
• Puoi apportare modifiche in fase di runtime all'impostazione della quota di un prodotto API e i valori delle quote vengono aggiornati automaticamente nei criteri delle quote che fanno riferimento al valore.

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

Per informazioni sulla configurazione dei prodotti API con limiti di quota, vedi Crea prodotti API.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in queste norme. Tieni presente che alcune combinazioni di elementi sono reciprocamente esclusive o non richieste. Consulta gli esempi 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 Recuperare 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 queste norme.

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 del criterio raggiunge questo limite valore, le chiamate successive vengono rifiutate finché il contatore non viene reimpostato.

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 figlio <Allow> diverso di <Class>, il criterio mantiene un contatore diverso.

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando l'attributo ref nel 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 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 tag figlio <Allow> diverso di <Class>, i criteri mantengono 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, la policy di quota gestisce due contatori di quota denominati peak_time e off_peak_time.

Attributi

Elemento <Interval>

Utilizza questo campo per specificare un numero intero (ad esempio 1, 2, 5, 60 e così via) che verrà abbinato all'unità TimeUnit specificata (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 significa che la quota verrà calcolata nell'arco di 24 ore.

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

Attributi

Elemento <TimeUnit>

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

Ad esempio, un Interval di 24 con un TimeUnit di 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,, specifica la data e l'ora in cui il contatore della quota inizierà il conteggio, indipendentemente dal fatto che siano state ricevute richieste da qualsiasi 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 contatore centrale e sincronizzarlo continuamente in tutti i processori di messaggi. I processori di messaggi possono trovarsi in zone di disponibilità e/o regioni diverse.

Se utilizzi il valore predefinito di false, potresti superare la quota perché il conteggio per ogni processore di messaggi 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 di quota distribuita. Ciò significa che l'aggiornamento del contatore viene eseguito contemporaneamente al controllo della quota in una richiesta all'API. Imposta questo valore su true se è essenziale non consentire chiamate API oltre la quota.

Imposta false per aggiornare il contatore della quota 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 è 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>

Utilizza questo parametro 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.

Elemento <AsynchronousConfiguration>/<SyncMessageCount>

Specifica il numero di richieste in tutti i processori di messaggi Apigee tra gli aggiornamenti delle quote.

<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 unico contatore applicato alla quota.

Questo elemento è trattato anche nel seguente post della community Apigee: Quota identifier across different policies.

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

Attributi

Elemento <MessageWeight>

Utilizza questo campo per specificare la ponderazione assegnata a ogni messaggio. Utilizza il peso dei messaggi 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 se fossero due volte più "pesanti" o costosi dei messaggi GET. Pertanto, imposti 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 MessageWeight per le richieste POST è 2, la quota consente 5 richieste POST in qualsiasi intervallo di 10 minuti. Qualsiasi richiesta aggiuntiva, POST o GET, prima del ripristino del contatore viene rifiutata.

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 eseguita una policy di quota. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili.

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Variabili di errore

Queste variabili vengono impostate quando il criterio attiva un errore. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

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

Criteri ResetQuota

Norme SpikeArrest

Confronto tra norme relative a quota, Spike Arrest e limite di frequenza simultanea