Criteri per le quote

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Una quota è un'assegnazione di richieste che un proxy API accetterà in un periodo di tempo, ad esempio minuto, ora, giorno, settimana o mese. I criteri per le quote gestiscono 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.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Quando un proxy API raggiunge il limite di quota, Apigee rifiuta le chiamate API successive e restituisce un messaggio di errore 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 i criteri ResetQuota.

Ad esempio, se una quota è definita come 10.000 messaggi al mese, la limitazione della frequenza inizia dopo il 10.000° messaggio. Non importa se 10.000 messaggi sono stati conteggiati il primo o l'ultimo giorno del mese.

Con Apigee, ogni chiamata API può essere ponderata in modo dinamico. Ad esempio, con un'API Large Language Model (LLM), puoi applicare un limite di frequenza in base al numero di token nella richiesta o nella risposta o in entrambe. Inoltre, i limiti delle quote possono essere dinamici, il che significa che puoi applicare quote più rigide quando il sistema è più occupato o allentare le quote durante le ore non di punta.

Una variante della norma relativa alla quota, la norma SpikeArrest, impedisce picchi (o raffiche) di traffico che possono essere causati da un improvviso aumento dell'utilizzo, da client con bug o da attacchi dannosi.

Puoi impostare la stessa quota per tutte le app che accedono al proxy API oppure puoi impostare limiti di quota diversi, a seconda di:

• Il prodotto che contiene il proxy API
• L'app che richiede l'API
• Lo sviluppatore dell'app
• Il servizio upstream
• Molti altri criteri
• Combinazioni di uno qualsiasi dei criteri disponibili

Non utilizzare il criterio per le quote per proteggerti dai picchi di traffico complessivi. A questo scopo, utilizza il criterio SpikeArrest.

Video

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

Tipi di criteri per le quote

Le norme relative alle quote supportano diversi modi in cui il contatore delle quote inizia e viene reimpostato. Puoi definire quale utilizzare con l'attributo type nell'elemento <Quota>, come mostrato nell'esempio seguente:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

I valori validi di type includono:

• calendar: configura una quota in base a un orario di inizio esplicito. Il contatore della quota per ogni app viene aggiornato in base ai valori <StartTime>, <Interval> e <TimeUnit> che hai impostato.
• rollingwindow: configura una quota che utilizza una "finestra mobile" per determinare l'utilizzo della quota. Con rollingwindow, determini le dimensioni della finestra con gli elementi <Interval> e <TimeUnit>, ad esempio 1 giorno. Quando arriva una richiesta, Apigee esamina l'ora esatta della richiesta (ad esempio le 17:01), conta il numero di richieste arrivate tra quell'ora e le 17:01 del giorno precedente (1 giorno) e determina se la quota è stata superata durante questo periodo.
• flexi: configura una quota che fa iniziare il conteggio quando viene ricevuto il primo messaggio di richiesta da un'app e si azzera in base ai valori <Interval> e <TimeUnit>.

La tabella seguente descrive quando viene reimpostata la quota per ciascun tipo:

Per type="calendar", devi specificare il valore di <StartTime>.

La tabella non descrive quando viene reimpostato il conteggio per il tipo rollingwindow. Questo perché le quote della finestra mobile funzionano in modo leggermente diverso, in base a una finestra temporale, ad esempio un'ora o un giorno. Per il tipo rollingwindow, il contatore non viene mai reimpostato, ma viene ricalcolato a ogni richiesta. Quando arriva una nuova richiesta, le norme determinano se la quota è stata superata nel periodo di tempo precedente.

Ad esempio, definisci un intervallo di due ore che consente 1000 richieste. Una nuova richiesta arriva alle 16:45.Il criterio calcola il conteggio delle quote per la finestra delle ultime due ore, 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.

Informazioni sui contatori delle quote

Quando un criterio per le quote viene eseguito in un flusso di proxy API, un contatore delle quote viene decrementato. Quando il contatore raggiunge il limite, non sono consentite ulteriori chiamate API associate a quel contatore. A seconda della configurazione, il criterio di quota può utilizzare uno o più contatori. È importante capire quando vengono utilizzati più contatori e come si comportano.

Come vengono conteggiate le quote per i prodotti API

Se il proxy API è incluso in un prodotto API, puoi configurare il criterio di quota in modo che utilizzi le regole di quota definite in quel prodotto. Un prodotto API può specificare regole di quota a livello di prodotto o a livello di singole operazioni.

Viene mantenuto un contatore di quota separato per ogni operazione definita in un prodotto API e vengono rispettate le seguenti regole:

• Se per un'operazione è definita una quota, le regole della quota dell'operazione hanno la precedenza sulle regole della quota definite a livello di prodotto. Viene creato un contatore di quota separato per ogni operazione. Qualsiasi chiamata API al percorso di un'operazione incrementa il relativo contatore.
• Se per un'operazione non è definita una quota, viene applicata la regola della quota a livello di prodotto; tuttavia, per l'operazione viene comunque mantenuto un contatore di quota separato. È importante capire in questo caso che, anche se la regola della quota viene presa dalla definizione a livello di prodotto, l'operazione mantiene comunque il proprio contatore.
• Se il prodotto API non include definizioni di quota, né a livello di prodotto né di operazione, si applicano le regole di quota specificate nei criteri. Tuttavia, anche in questo caso, viene mantenuto un contatore di quota separato per ogni operazione nel prodotto API.

Le sezioni seguenti descrivono in modo più dettagliato le opzioni e il comportamento dei contatori.

Configurazione dei contatori a livello di proxy API

È possibile configurare un prodotto API per mantenere un conteggio della quota a livello di proxy API. In questo caso, la configurazione della quota specificata a livello di prodotto API viene condivisa da tutte le operazioni per le quali non è specificata una quota propria. L'effetto di questa configurazione è la creazione di un contatore globale a livello di proxy API per questo prodotto API.

Per ottenere questa configurazione, devi utilizzare l'API Apigee/apiproducts per creare o aggiornare il prodotto e impostare l'attributo quotaCountScope su PROXY nella richiesta di creazione o aggiornamento. Con la configurazione PROXY, tutte le operazioni definite per il prodotto API associate allo stesso proxy e che non hanno un proprio contatore condivideranno lo stesso contatore di quota impostato a livello di prodotto API.

Nella Figura 1, le operazioni 1 e 2 sono associate a Proxy1, mentre le operazioni 4 e 5 sono associate a Proxy3. Poiché quotaCounterScope=PROXY è impostato nel prodotto API, ciascuna di queste operazioni condivide l'impostazione della quota a livello di prodotto API. Tieni presente che, sebbene queste operazioni condividano la stessa configurazione delle quote, utilizzano contatori separati in base alla loro associazione proxy. D'altra parte, l'operazione 3 ha una propria configurazione della quota impostata e pertanto non è interessata dal flag quotaCounterScope.

Figura 1: utilizzo del flag quotaCounterScope

Per impostazione predefinita, se un'operazione non ha una quota definita, viene applicata la regola di quota a livello di prodotto; tuttavia, viene comunque mantenuto un contatore di quota separato per l'operazione.

Come vengono conteggiate le quote se non vengono utilizzati prodotti API

Se non è associato alcun prodotto API a un proxy API, un criterio per le quote mantiene 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 nel flusso di un proxy API, che può involontariamente causare l'esaurimento delle quote più rapidamente del previsto, è un anti-pattern descritto in Introduzione agli anti-pattern.

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.

Creazione di più contatori tramite la configurazione dei criteri

Puoi utilizzare gli elementi <Class> o <Identifier> nel criterio per le quote per definire più contatori unici in un unico criterio. Utilizzando questi elementi, una singola norma può mantenere contatori diversi in base all'app che effettua la richiesta, al suo sviluppatore, 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, 2021-02-04 rappresenta il 4 febbraio 2021.

L'ora del giorno è definita come ore, minuti e secondi nel seguente formato: hours:minutes:seconds. Ad esempio, 23:59:59 rappresenta 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, 2021-02-04 24:00:00 corrisponde alla stessa data e ora di 2021-02-05 00:00:00. Quest'ultima è di solito la notazione preferita.

Recupero delle impostazioni di quota dalla configurazione del prodotto API

Puoi impostare i 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 Gestione dei prodotti API.

Configurazione dei contatori di quota condivisi

Nel caso semplice, il criterio per le quote incrementa il contatore una volta per ogni richiesta inviata a un proxy API durante l'elaborazione della richiesta iniziale. In alcuni casi, potresti voler verificare se la quota viene superata durante la gestione iniziale della richiesta in entrata, ma incrementare il contatore solo durante la gestione della risposta. Ciò ha senso quando il costo o il peso della chiamata API può essere noto solo dopo la risposta del sistema upstream o di destinazione. Nel caso di un'API LLM, le dimensioni della risposta in token potrebbero determinare il costo. Nel caso di un'API BigQuery, il total_slot_ms nella risposta potrebbe determinare il costo.

Tre elementi dei criteri per le quote (<SharedName>, <CountOnly> e <EnforceOnly>), se utilizzati insieme, ti consentono di personalizzare i criteri per le quote per applicare la quota alla richiesta in entrata e accumulare conteggi in base alla quota in base alle informazioni derivate dalle risposte di destinazione.

Ad esempio, supponi di avere un proxy API che utilizza un LLM come target e di voler applicare una quota di 100.000 token all'ora. Le risposte del LLM forniscono un valore totalTokenCount. Per farlo:

• Collega un criterio Quota al flusso di richiesta ProxyEndpoint con l'elemento <SharedName> impostato con un valore di nome e l'elemento <EnforceOnly> impostato su true.
• Al flusso di risposta ProxyEndpoint, collega un criterio ExtractVariables per estrarre il valore totalTokenCount dalla risposta ricevuta dal target LLM.
• Collega un secondo criterio per le quote al flusso di risposta ProxyEndpoint con l'elemento <SharedName> impostato sullo stesso valore del nome del primo criterio per le quote e l'elemento <CountOnly> impostato su true. Imposta l'elemento <MessageWeight> per utilizzare il valore totalTokenCount estratto.

Per un esempio che mostra come utilizzare i contatori condivisi, consulta Contatori condivisi nella sezione Esempi.

Esempi

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

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

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>Quota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>EV-Token-Count</Name>
      </Step>
      <Step>
        <Name>Quota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

<Quota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</Quota>

<ExtractVariables name='EV-Token-Count'>
  <Source>response</Source>
  <VariablePrefix>extracted</VariablePrefix>
  <JSONPayload>
    <Variable name='tokenCount'>
      <JSONPath>$[1].usageMetadata.totalTokenCount</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<Quota name="Quota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first Quota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <MessageWeight ref="extracted.tokenCount"/>
</Quota>

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

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

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

Elemento <Quota>

Di seguito sono riportati gli attributi e gli elementi secondari di <Quota>. Tieni presente che alcune combinazioni di elementi sono reciprocamente esclusive o non richieste. Consulta gli esempi per un utilizzo specifico.

Le variabili verifyapikey.my-verify-key-policy.apiproduct.* riportate di seguito sono disponibili per impostazione predefinita quando viene utilizzata una norma VerifyAPIKey denominata my-verify-key-policy per controllare la chiave API dell'app nella richiesta. I valori delle variabili provengono dalle impostazioni di quota del prodotto API a cui è associata la chiave, come descritto in Recuperare le impostazioni di quota dalla configurazione del prodotto API.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <Allow>
          <Class ref="request.queryparam.time_variable">
            <Allow class="peak_time" count="5000"/>
            <Allow class="off_peak_time" count="1000"/>
          </Class>
       </Allow>
       <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

I seguenti attributi sono specifici di queste norme:

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

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

<Allow>

Specifica il limite di conteggio per la quota. Se il contatore del criterio raggiunge questo limite, le chiamate successive vengono rifiutate finché il contatore non viene reimpostato.

Può contenere anche un elemento <Class> che condiziona l'elemento <Allow> in base a una variabile di flusso.

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.

Puoi anche specificare un elemento <Class> come elemento secondario di <Allow> per determinare il conteggio consentito del criterio in base a una variabile di flusso. Apigee associa il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

La seguente tabella elenca gli attributi di <Allow>:

<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>, i criteri mantengono un contatore diverso.

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando l'attributo ref dell'elemento <Class>. Apigee utilizza quindi il valore della variabile di flusso per selezionare uno degli elementi secondari <Allow> per determinare il conteggio consentito del criterio. Apigee associa il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

In questo esempio, il contatore della quota corrente è determinato dal valore del parametro di query time_variable passato con ogni richiesta. Questa variabile può avere un valore di peak_time o off_peak_time. Se il parametro di query contiene un valore non valido, il criterio restituisce un errore di violazione della quota.

La seguente tabella elenca gli attributi di <Class>:

<Allow> (figlio di <Class>)

Specifica il limite per un contatore di quota definito dall'elemento <Class>. Per ogni tag figlio <Allow> diverso di <Class>, le norme mantengono un contatore diverso.

Ad esempio:

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow count="5000"/>
        <Allow count="1000"/>
      </Class>
    </Allow>

In questo esempio, il criterio di quota gestisce due contatori di quota denominati peak_time e off_peak_time. Quale di questi viene utilizzato dipende dal parametro di query passato, come mostrato nell'esempio <Class>.

La seguente tabella elenca gli attributi di <Allow>:

<Interval>

Specifica il numero di periodi di tempo in cui vengono calcolate le quote.

Utilizza questo campo per specificare un numero intero (ad esempio 1, 2, 5, 60 e così via) che verrà abbinato all'elemento <TimeUnit> specificato (minuto, ora, giorno, settimana o mese) per determinare un periodo di tempo durante il quale Apigee calcola l'utilizzo della quota.

Ad esempio, un intervallo di 24 con un <TimeUnit> di hour significa che la quota verrà calcolata nell'arco di 24 ore.

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

La seguente tabella elenca gli attributi di <Interval>:

<TimeUnit>

Specifica l'unità di tempo applicabile alla quota.

Scegli tra minute, hour, day, week, month o year.

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>

La seguente tabella elenca gli attributi di <TimeUnit>:

<StartTime>

Quando type è impostato su calendar, specifica la data e l'ora in cui inizia il conteggio del contatore della quota, indipendentemente dal fatto che siano state ricevute richieste da qualsiasi app.

Ad esempio:

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

<Distributed>

Determina se Apigee utilizza uno o più nodi per elaborare le richieste.

Imposta true per specificare che il criterio deve mantenere un contatore centrale e sincronizzarlo continuamente su tutti i nodi. I nodi possono trovarsi in zone di disponibilità e/o regioni diverse.

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

<Distributed>false</Distributed>

Per garantire che i contatori siano sincronizzati e aggiornati a ogni richiesta, imposta <Distributed> e <Synchronous> su true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

Determina se aggiornare in modo sincrono un contatore di quota distribuita.

Imposta su true per aggiornare in modo sincrono un contatore di quota distribuita. Ciò significa che gli aggiornamenti ai contatori vengono eseguiti contemporaneamente alla verifica della quota in una richiesta all'API. Imposta 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 il contatore della quota nel repository centrale viene aggiornato in modo asincrono. 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>

<AsynchronousConfiguration>

Configura l'intervallo di sincronizzazione tra i contatori delle quote distribuite quando l'elemento di configurazione del criterio <Synchronous> non è presente o è presente e impostato su false. Apigee ignora questo elemento quando <Synchronous> è impostato su true.

Puoi specificare il comportamento di sincronizzazione utilizzando gli elementi secondari <SyncIntervalInSeconds> o <SyncMessageCount>. Utilizza uno o entrambi gli elementi. Ad esempio,

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

• Quando è presente solo <SyncIntervalInSeconds>, la quota viene sincronizzata ogni N secondi, dove N è il valore specificato nell'elemento, indipendentemente dal numero di messaggi gestiti.
• Quando è presente solo <SyncMessageCount>, la quota si sincronizza ogni M messaggi, dove M è il valore specificato nell'elemento o ogni 10 secondi, a seconda dell'evento che si verifica per primo.
• Quando sono presenti entrambi gli elementi, la quota viene sincronizzata ogni M messaggi o ogni N secondi, a seconda dell'evento che si verifica per primo.
• Quando <AsynchronousConfiguration> non è presente o non è presente alcun elemento secondario, la quota viene sincronizzata ogni 10 secondi, indipendentemente dal numero di messaggi gestiti.

<SyncIntervalInSeconds>

Esegue 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 >= 10 secondi, come descritto in Limiti.

<SyncMessageCount>

Specifica il numero di richieste da elaborare prima di sincronizzare il contatore della quota.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Utilizzando la configurazione in questo esempio, su ogni nodo il conteggio della quota verrà sincronizzato dopo ogni 5 richieste o ogni 10 secondi, a seconda dell'evento che si verifica per primo.

<Identifier>

Configura il criterio per creare contatori unici in base a una variabile di flusso.

Tramite l'elemento Identificatore, puoi assegnare i conteggi delle chiamate a bucket distinti definiti dal valore di una variabile di flusso. Ad esempio, puoi utilizzare la variabile developer.id, che viene compilata dopo una norma VerifyAPIKey, per applicare un limite di quota a tutte le istanze di tutte le app create da ogni sviluppatore specifico oppure puoi utilizzare client_id per applicare un limite di quota a ogni app specifica. La configurazione per quest'ultima è la seguente:

<Identifier ref="client_id"/>

Puoi fare riferimento a una variabile personalizzata che potresti impostare con il criterio AssignMessage o il criterio JavaScript oppure a una variabile impostata implicitamente, ad esempio quelle impostate dal criterio VerifyAPIKey o dal criterio VerifyJWT. Per ulteriori informazioni sulle variabili, consulta Utilizzare le variabili di flusso e, per un elenco delle variabili note definite da Apigee, consulta il riferimento alle variabili di flusso.

Se non utilizzi questo elemento, il criterio assegna tutti i conteggi delle chiamate a un unico contatore per il criterio per le quote specifico.

Questo elemento è trattato anche in Come funziona la norma relativa alla quota quando non viene specificato alcun identificatore?

La tabella seguente descrive gli attributi di <Identifier>:

<MessageWeight>

Specifica il costo assegnato a ogni messaggio ai fini della quota. Utilizza questo elemento per assegnare un impatto diverso alle richieste API in base al loro contenuto o al valore della chiamata.

Ad esempio, quando Apigee gestisce un'API Large Language Model (LLM), puoi utilizzare il numero di token nella richiesta o nella risposta, o in entrambe, come <MessageWeight>.

Oppure, se vuoi che i messaggi POST vengano conteggiati come se costassero il doppio rispetto ai messaggi GET, imposta <MessageWeight> su 2 per un messaggio POST e su 1 per un messaggio GET. Supponiamo che la quota sia di 10 messaggi al minuto e che il proxy elabori 5 richieste POST nei primi 35 secondi. Il proxy rifiuterà qualsiasi richiesta aggiuntiva, POST o GET, finché il contatore non viene reimpostato.

Un valore che rappresenta <MessageWeight> deve essere specificato utilizzando una variabile di flusso e può essere estratto da intestazioni HTTP, parametri di ricerca, un payload di richiesta XML o JSON o qualsiasi altra variabile di flusso. Ad esempio, puoi estrarre il valore da un payload di risposta in una variabile denominata extracted.message_weight e poi utilizzarlo per <MessageWeight>:

<MessageWeight ref="extracted.message_weight"/>

Se la variabile di flusso viene risolta in 0, la richiesta non influirà sul contatore.

<UseQuotaConfigInAPIProduct>

Definisce le impostazioni della quota per un prodotto API, ad esempio le unità di tempo, l'intervallo e il massimo consentito.

Se aggiungi l'elemento <UseQuotaConfigInAPIProduct> alla norma Quota, Apigee ignora gli elementi secondari <Allow>, <Interval> e <TimeUnit> di <Quota>.

L'elemento <UseQuotaConfigInAPIProduct> è semplicemente un contenitore per le impostazioni predefinite che definisci utilizzando l'elemento <DefaultConfig>, come mostrato nell'esempio seguente:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Puoi utilizzare l'attributo stepName per fare riferimento a un'operazione di criterio VerifyAPIKey o a un'operazione di criterio ValidateToken del criterio OAuthv2 nel flusso.

La tabella seguente descrive gli attributi di <UseQuotaConfigInAPIProduct>:

Per ulteriori informazioni, consulta le seguenti risorse:

• <DefaultConfig>
• Che cos'è un prodotto API?
• Gestione dei prodotti API

<DefaultConfig>

Contiene i valori predefiniti per la quota di un prodotto API. Quando definisci un <DefaultConfig>, tutti e tre gli elementi secondari sono obbligatori.

È possibile definire questi valori sia nell'operazione del prodotto API (tramite l'interfaccia utente o l'API API products) sia nel criterio Quota. Se lo fai, tuttavia, le impostazioni del prodotto API hanno la precedenza e le impostazioni della norma relativa alla quota vengono ignorate.

La sintassi di questo elemento è la seguente:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

L'esempio seguente specifica una quota di 10.000 ogni settimana:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Per ulteriori informazioni, consulta le seguenti risorse:

• Che cos'è un prodotto API?
• Gestione dei prodotti API

<SharedName>

Identifica questo criterio per le quote come condiviso. Tutti i criteri per le quote in un proxy API con lo stesso valore <SharedName> condividono lo stesso contatore di quote sottostante. Se questo elemento è presente, deve essere presente anche l'elemento <EnforceOnly> o l'elemento <CountOnly>.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori di quote condivise.

<CountOnly>

Inserisci una policy Quota con questo elemento impostato su true in un passaggio del flusso di risposta ProxyEndpoint per incrementare il contatore della quota sottostante senza inviare un errore al client quando il limite di quota viene superato. Se questo elemento è presente, deve essere presente anche l'elemento <SharedName> e non deve essere presente l'elemento <EnforceOnly>.

Per ulteriori informazioni ed esempi, vedi Configurazione dei contatori di quota condivisa.

<EnforceOnly>

Inserisci un criterio per le quote con questo elemento impostato su true nel flusso di richiesta di un proxy API per applicare una quota senza incrementare il contatore delle quote. Questa configurazione consente l'applicazione differita dei limiti di frequenza in base ai pesi dei messaggi che possono essere noti solo nel flusso di risposta. Se questo elemento è presente, deve essere presente anche <SharedName> e l'elemento <CountOnly> non deve essere presente.

Per ulteriori informazioni ed esempi, vedi Configurazione dei contatori di quota condivisa.

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando viene eseguita una policy di quota. Per ulteriori informazioni, consulta Riferimento alle variabili di flusso.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione dei guasti.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione della policy.

Errori di deployment

Variabili di errore

Queste variabili vengono impostate quando questo criterio genera un errore. Per saperne di più, consulta 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"
   }
}

Regola di errore di esempio

<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 i criteri per le quote e Spike Arrest