Criteri per le quote

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione 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 un periodo di tempo, ad esempio minuto, ora, giorno, settimana o mese. Puoi impostare la quota in modo che uguale 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 Quota per proteggerti dai picchi di traffico complessivi. Per farlo, usa la funzione Spike Arrest . Vedi Arresto dei picchi .

Video

Questi video introducono la gestione delle quote con i criteri per le quote:

Esempi

Questi esempi di codice dei criteri illustrano 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'allocazione di messaggi di richiesta che un proxy API può gestire in un periodo di tempo. come minuto, ora, giorno, settimana o mese. Il criterio gestisce i contatori che calcolano il numero di richieste ricevute dal proxy API. Questa funzionalità consente ai provider API di applicare limiti Il numero di chiamate API effettuate dalle app in un intervallo di tempo. Utilizzando i criteri per le quote, puoi Ad esempio, limita 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 tale periodo; nessuna area di richieste aggiuntiva consentita fino al contatore della quota viene reimpostata automaticamente alla fine dell'intervallo di tempo specificato o finché la quota non viene esplicitamente reimpostata usando Reimposta quota .

Una variante della quota chiamata SpikeArrest impedisce picchi di traffico (o burst) che possono essere causate da un improvviso aumento dell'utilizzo, da client con bug o da attacchi dannosi. Per ulteriori informazioni informazioni su SpikeArrest, consulta le norme relative all'arresto degli attacchi.

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 usano la stessa configurazione dei criteri per le 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 il contatore della quota all'avvio e al reset, come illustrato nella tabella seguente:

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

La tabella non elenca il valore per il tipo rollingwindow. Finestra temporale continua funzionano impostando la dimensione di una "finestra", ad esempio una finestra di un'ora o di un giorno. Quando quando arriva una nuova richiesta, il criterio determina se la quota è stata superata in passato "finestra" del tempo.

Ad esempio, definisci una finestra di due ore che consente 1000 richieste. Una nuova richiesta alle 16:45.Il criterio calcola il conteggio delle quote delle ultime due ore, ovvero il numero di richieste a partire dalle 14:45. Se il limite della quota non è stato superato nel di due ore, la richiesta è consentita.

Un minuto dopo, alle 16:46, è in arrivo un'altra richiesta. Ora il criterio calcola numero di quote dalle 14:46 per determinare se il limite è stato superato.

Per il tipo rollingwindow, il contatore non viene mai reimpostato, ma viene 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 farvi riferimento in un proxy API. Il nome del contatore della quota è basato su l'attributo name del criterio.

Ad esempio, crei un criterio per le quote denominato MyQuotaPolicy con un limite di 5 richieste e lo collochi su più flussi (flusso A, B e C) nel proxy API. Anche se utilizzato in più flussi, mantiene un unico contatore che viene aggiornato da tutte le istanze norme:

• Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore è uguale a 1
• Viene eseguito il flusso B -> MyQuotaPolicy viene eseguito e il relativo contatore è = 2
• Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore è = 3
• Viene eseguito il flusso C -> MyQuotaPolicy viene eseguito e il relativo contatore è uguale a 4
• Viene eseguito il flusso A -> MyQuotaPolicy viene eseguito e il relativo contatore è pari a 5

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

Utilizzare lo stesso criterio per le quote in più di una posizione in un flusso proxy API, con la possibilità causare involontariamente l'esaurimento della quota più velocemente del previsto è un anti-pattern descritto in Il libro degli antipattern Apigee Edge.

In alternativa, puoi definire più criteri per le quote nel proxy API e utilizzare un altro in ogni flusso. Ogni criterio per le quote gestisce il proprio contatore, basato su l'attributo name del criterio.

In alternativa, utilizza <Class> o <Identifier> elementi in il criterio per le quote per definire più contatori univoci in un unico criterio. Utilizzando questi , un'unica norma può mantenere diversi contatori in base all'app che effettua la richiesta, lo sviluppatore dell'app che effettua la richiesta, un ID client o un altro identificatore client e altro ancora. Consulta le esempi sopra per ulteriori informazioni sull'uso Elementi <Class> o <Identifier>.

Notazione dell'ora

Tutti i tempi di quota sono impostati sul valore Coordinated Universal Ora (UTC).

La notazione dell'ora delle quote segue la notazione della data standard internazionale definita in Internazionale Standard ISO 8601.

Le date sono definite 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 espressa in ore, minuti e secondi nel seguente formato: hours:minutes:seconds. Ad esempio, 23:59:59 rappresenta il momento in cui secondo prima di mezzanotte.

Tieni presente che sono disponibili due notazioni, 00:00:00 e 24:00:00, distinguere le due mezze notti che possono essere associate a una sola data. Di conseguenza, 2015-02-04 24:00:00 corrisponde alla stessa data e ora di 2015-02-05 00:00:00. Il secondo è di solito la notazione preferita.

Recupero delle impostazioni della quota dalla configurazione del prodotto API

Puoi impostare limiti di quota nelle configurazioni dei prodotti API. Questi limiti non vengono automaticamente applicare la quota. Puoi però fare riferimento alle impostazioni delle quote dei prodotti in un criterio per le quote. Ecco alcuni esempi vantaggi dell'impostazione di una quota sul prodotto per far riferimento ai criteri di quota:

• 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 in un prodotto API e ai criteri sulle quote che fanno riferimento al valore, i valori di quota vengono automaticamente aggiornati.

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

Per informazioni sulla configurazione di prodotti API con limiti di quota, consulta Creare prodotti API.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in questo criterio. Tieni presente che alcuni elementi si escludono a vicenda o non sono obbligatorie. Visualizza gli esempi per l'utilizzo specifico. La Le seguenti verifyapikey.VerifyAPIKey.apiproduct.* variabili sono disponibili per impostazione predefinita quando un criterio di verifica della chiave API denominato "VerifyAPIKey" viene utilizzato per controllare la chiave API dell'app nella richiesta. I valori della variabile provengono dalle impostazioni della quota sul prodotto API a cui è associata la chiave come descritto in Recupero delle impostazioni di quota dal prodotto API configurazione.

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

<Quota> attributi

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Gli attributi riportati di seguito sono specifici di questo criterio.

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

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

<Allow> elemento

Specifica il limite di conteggio per la quota. Se il contatore per il criterio raggiunge questo limite le chiamate successive vengono rifiutate fino a quando 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 sia countRef, countRef ha la priorità. Se countRef non si risolve in fase di runtime, il valore di È in uso count.

Attributi

<Allow>/<Class> elemento

L'elemento <Class> ti consente di condizionare il valore dell'elemento <Allow> in base al valore di una variabile di flusso. Per ogni tag secondario <Allow> di <Class>, il criterio mantiene uno diverso contatore.

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando il metodo ref al tag <Class>. Edge utilizza quindi il valore di flusso per selezionare uno dei <Allow> tag secondari per determinare il del criterio. Il perimetro associa il valore della variabile di flusso a 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 time_variable parametro di query passato a ogni richiesta. La 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

<Allow>/<Class>/<Allow> elemento

L'elemento <Allow> specifica il limite per un contatore delle quote definita dall'elemento <Class>. Per ogni un altro tag secondario <Allow> di <Class>, mantiene uno diverso contatore.

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

Attributi

<Interval> elemento

Da utilizzare per specificare un numero intero (ad esempio, 1, 2, 5, 60 e così via) che verrà associato al valore TimeUnit specifichi (minuto, ora, giorno, settimana o mese) per determinare un orario durante il quale Edge calcola l'utilizzo della quota.

Ad esempio, Interval di 24 con un TimeUnit di hour significa che la quota sarà calcolati nell'arco di 24 ore.

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

Attributi

<TimeUnit> elemento

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

Ad esempio, Interval di 24 con un TimeUnit di hour significa che la quota sarà calcolati nell'arco di 24 ore.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Attributi

<StartTime> elemento

Se il criterio type è impostato su calendar,, viene specificata la data e l'ora in cui inizierà il conteggio il contatore della quota, indipendentemente dal fatto che siano state ricevuto da qualsiasi app.

Devi fornire un valore StartTime esplicito quando type è impostato in modo esplicito a calendar, non puoi utilizzare un riferimento a una variabile di flusso, se specifichi un valore StartTime se non è impostato alcun valore type, riceverai un .

Ad esempio:

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

<Distribuito> elemento

Un'installazione di Edge può utilizzare uno o più processori di messaggi per elaborare le richieste. Imposta questo su true per specificare che il criterio deve mantenere una e sincronizzarlo continuamente su tutti i processori di messaggi. I processori di messaggi possono essere in zone di disponibilità e/o regioni.

Se utilizzi il valore predefinito false, potresti superare la quota per il conteggio per ciascun processore di messaggi non viene 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>

&lt;Synchronous&gt; elemento

Imposta su true per aggiornare un contatore di quota distribuita in modo sincrono. Questo significa che l'aggiornamento del contatore viene eseguito nello stesso momento in cui viene controllata la quota su una richiesta all'API. Imposta su true se è essenziale non consentire nessuna API oltre la quota.

Imposta su false per aggiornare il contatore della quota in modo asincrono. Ciò significa è possibile che alcune chiamate API che superano la quota vengano andate a buon fine, a seconda di quando il contatore delle quote nel repository centrale viene aggiornato in modo asincrono. Tuttavia, non affronterai il potenziale impatto sulle prestazioni associato agli aggiornamenti sincroni.

L'intervallo di aggiornamento asincrono predefinito è di 10 secondi. Utilizza la AsynchronousConfiguration per configurare questo comportamento asincrono.

<Synchronous>false</Synchronous>

&lt;AsynchronousConfiguration&gt; elemento

Configura l'intervallo di sincronizzazione tra i contatori delle quote distribuite quando il criterio l'elemento di configurazione <Synchronous> non è presente o non è presente e impostato a false.

Puoi eseguire la sincronizzazione dopo un periodo di tempo o il numero di messaggi utilizzando il metodo Elementi secondari SyncIntervalInSeconds o SyncMessageCount. Si escludono a vicenda. Ad esempio,

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

o

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

&lt;AsynchronousConfiguration&gt;/&lt;SyncIntervalInSeconds&gt; elemento

Utilizza questa opzione per eseguire l'override del comportamento predefinito in cui gli aggiornamenti asincroni vengono eseguiti dopo un di 10 secondi.

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

L'intervallo di sincronizzazione deve essere maggiore o uguale a 10 secondi, come descritto in Limiti.

&lt;AsynchronousConfiguration&gt;/&lt;SyncMessageCount&gt; elemento

Specifica il numero di richieste tra tutti i processori di messaggi Apigee tra la quota aggiornamenti.

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

In questo esempio viene specificato che il conteggio delle quote viene aggiornato ogni 5 richieste in ogni piattaforma Apigee Processore di messaggi Edge.

&lt;Identifier&gt; elemento

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

Se non utilizzi questo elemento, la norma utilizza un unico contatore applicato a la 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

&lt;MessageWeight&gt; elemento

Utilizzalo per specificare il peso assegnato a ciascun messaggio. Usa il peso del messaggio per aumentare l'impatto di richieste che, ad esempio, consumano più risorse di calcolo di altre.

Ad esempio, se vuoi che i messaggi POST siano il doppio più "pesanti" o costoso, come GET messaggi. Di conseguenza, imposti MessageWeight su 2 per POST e 1 per SCARICA. Puoi anche impostare MessageWeight su 0 in modo che la richiesta non influisce sul contatore. In questo esempio, se la quota è di 10 messaggi al minuto il valore MessageWeight per le richieste POST è 2, la quota consente cinque richieste POST in un intervallo di 10 minuti. Per qualsiasi richiesta aggiuntiva, POST o GET, prima che il contatore venga reimpostato.

Un valore che rappresenta MessageWeight deve essere specificato da un flusso e può essere estratta da intestazioni HTTP, parametri di ricerca, una 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 un criterio per le quote . Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento per le 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

Criterio ResetQuota

SpikeArrest norme

Confronto Norme relative a quote, picco e limiti di frequenza simultanei