Criterio SpikeArrest

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio SpikeArrest protegge dai picchi di traffico con l'elemento <Rate>. Questo elemento limita il numero di richieste elaborate da un proxy API e inviate a un backend, proteggendo da ritardi nelle prestazioni e tempi di inattività.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Differenza tra SpikeArrest e Quota

Il criterio per le quote configura il numero di messaggi di richiesta che un'app client può inviare a un'API nell'arco di un'ora, un giorno, una settimana o un mese. I criteri per le quote applicano limiti di consumo alle app client mantenendo un contatore distribuito che conteggia le richieste in entrata.

Utilizza Quota per applicare contratti commerciali o SLA con sviluppatori e partner, piuttosto che per la gestione del traffico operativo. Utilizza SpikeArrest per proteggerti da picchi improvvisi di traffico API. Vedi anche Confronto tra le policy Quota e SpikeArrest.

Video

Questi video illustrano i casi d'uso di queste norme:

Perché è necessario

Confrontare i criteri per le quote

Elemento <SpikeArrest>

Definisce il criterio SpikeArrest.

Valore predefinito	Consulta la scheda Policy predefinita di seguito.
Obbligatorio?	Facoltativo
Tipo	Oggetto complesso
Elemento principale	n/a
Elementi secondari	<Identifier> <MessageWeight> <Rate> (obbligatorio) <UseEffectiveCount>

Sintassi

L'elemento <SpikeArrest> utilizza la seguente sintassi:

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Norme predefinite

L'esempio seguente mostra le impostazioni predefinite quando aggiungi una policy SpikeArrest al tuo flusso nell'interfaccia utente:

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Ritirato	Questo attributo è stato ritirato.

Esempi

Gli esempi seguenti mostrano alcuni dei modi in cui puoi utilizzare la policy Spike Arrest:

Esempio 1

L'esempio seguente imposta la frequenza su cinque al secondo:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Questo criterio di esempio consente un massimo di 5 richieste al secondo. Tramite lo smoothing, viene applicato un massimo di una richiesta ogni intervallo di 200 millisecondi (1000/5).

Esempio 2

L'esempio seguente imposta la frequenza su 12 al minuto:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Questa policy di esempio consente un massimo di 12 richieste al minuto alla velocità di una richiesta ogni 5 secondi (60/12). Se nell'intervallo di 5 secondi sono presenti più richieste, queste sono consentite (nessun livellamento) a condizione che il numero di richieste sia inferiore al limite di frequenza configurato di 12 al minuto.

Esempio 3

L'esempio seguente limita le richieste a 12 al minuto (una richiesta consentita ogni cinque secondi, ovvero 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Inoltre, l'elemento <MessageWeight> accetta un valore personalizzato (l'intestazione weight) che regola i pesi dei messaggi per app o client specifici. Ciò fornisce un controllo aggiuntivo sulla limitazione per le entità identificate con l'elemento <Identifier>.

Esempio 4

L'esempio seguente indica a SpikeArrest di cercare un valore di runtime impostato tramite la richiesta passata come variabile di flusso request.header.runtime_rate:

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Il valore della variabile di flusso deve essere nel formato intpm o intps.

Per provare questo esempio, esegui una richiesta come la seguente:

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

Suggerimento:consulta Come posso utilizzare i prodotti API per impostare i limiti di Spike Arrest?, che spiega come impostare la frequenza SpikeArrest utilizzando le variabili personalizzate impostate in un prodotto API.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SpikeArrest>.

<DisplayName>

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

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito	N/D
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<Identifier>

Consente di scegliere come raggruppare le richieste in modo che la policy SpikeArrest possa essere applicata in base al client. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, nel qual caso le richieste di ciascun sviluppatore verranno conteggiate ai fini della propria frequenza SpikeArrest e non tutte le richieste al proxy.

Utilizzalo in combinazione con l'elemento <MessageWeight> per un controllo più granulare della limitazione delle richieste.

Se lasci vuoto l'elemento <Identifier>, viene applicato un limite di frequenza a tutte le richieste nel proxy API.

Valore predefinito	n/a
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<SpikeArrest>
Elementi secondari	Nessuno

Sintassi

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

Esempio 1

L'esempio seguente applica il criterio SpikeArrest per ID sviluppatore:

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

La tabella seguente descrive gli attributi di <Identifier>:

Attributo	Descrizione	Predefinito	Presenza
ref	Identifica la variabile in base alla quale SpikeArrest raggruppa le richieste in entrata. Puoi utilizzare qualsiasi variabile di flusso per indicare un client univoco, ad esempio quelle disponibili con la policy VerifyAPIKey. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage.	n/a	Obbligatorio

Questo elemento è trattato anche in questo post della community Apigee.

<MessageWeight>

Specifica la ponderazione definita per ogni messaggio. Il peso del messaggio modifica l'impatto di una singola richiesta sul calcolo della frequenza SpikeArrest. Il peso del messaggio può essere qualsiasi variabile di flusso, ad esempio un'intestazione HTTP, un parametro di query, un parametro del modulo o il contenuto del corpo del messaggio. Puoi anche utilizzare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage.

Utilizzalo in combinazione con <Identifier> per limitare ulteriormente le richieste di client o app specifici.

Ad esempio, se SpikeArrest <Rate> è 10pm e un'app invia richieste con un peso di 2, sono consentiti solo cinque messaggi al minuto da questo client perché ogni richiesta conta come 2.

Valore predefinito	n/a
Obbligatorio?	Facoltativo
Tipo	Numero intero
Elemento principale	<SpikeArrest>
Elementi secondari	Nessuno

Sintassi

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

Esempio 1

L'esempio seguente limita le richieste a 12 al minuto (una richiesta consentita ogni cinque secondi, ovvero 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

In questo esempio, <MessageWeight> accetta un valore personalizzato (l'intestazione weight nella richiesta) che regola i pesi dei messaggi per clienti specifici. Ciò fornisce un controllo aggiuntivo sulla limitazione per le entità identificate con l'elemento <Identifier>.

La tabella seguente descrive gli attributi di <MessageWeight>:

Attributo	Descrizione	Presenza	Predefinito
ref	Identifica la variabile di flusso che contiene il peso del messaggio per il client specifico. Può trattarsi di qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio. Per ulteriori informazioni, consulta Riferimento alle variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage.	Obbligatorio	N/D

<Rate>

Specifica la velocità con cui limitare i picchi (o i burst) di traffico impostando il numero di richieste consentite a intervalli di un minuto o un secondo. Puoi utilizzare questo elemento anche in combinazione con <Identifier> e <MessageWeight> per limitare il traffico in modo uniforme in fase di runtime accettando i valori del client. Utilizza l'elemento <UseEffectiveCount> per impostare l'algoritmo di limitazione di frequenza utilizzato dalla policy.

Nota:l'utilizzo di <UseEffectiveCount> con un valore o false non è supportato per nessuna organizzazione Apigee o per le organizzazioni Apigee ibride che eseguono carichi di lavoro di produzione. Per saperne di più, vedi <UseEffectiveCount>.

Consulta la sezione SpikeArrest della pagina Limiti per i limiti di frequenza massimi che puoi specificare.

Valore predefinito	n/a
Obbligatorio?	Obbligatorio
Tipo	Numero intero
Elemento principale	<SpikeArrest>
Elementi secondari	Nessuno

Sintassi

Puoi specificare le tariffe in uno dei seguenti modi:

• Una tariffa statica che specifichi come corpo dell'elemento <Rate>
• Un valore variabile, che può essere passato dal client; identifica il nome della variabile di flusso utilizzando l'attributo ref

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

I valori di tasso validi (definiti come valore di variabile o nel corpo dell'elemento) devono rispettare il seguente formato:

• intps (numero di richieste al secondo, uniformato in intervalli di millisecondi)
• intpm (numero di richieste al minuto, uniformato in intervalli di secondi)

Il valore di int deve essere un numero intero positivo diverso da zero.

Esempio 1

L'esempio seguente imposta la frequenza su cinque richieste al secondo:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Il criterio uniforma la frequenza a una richiesta consentita ogni 200 millisecondi (1000/5).

Esempio 2

L'esempio seguente imposta la velocità su 12 richieste al minuto:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Questa policy di esempio uniforma la frequenza a una richiesta consentita ogni cinque secondi (60/12).

La tabella seguente descrive gli attributi di <Rate>:

Attributo	Descrizione	Presenza	Predefinito
ref	Identifica una variabile di flusso che specifica la tariffa. Può trattarsi di qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio oppure un valore come una KVM. Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso. Puoi anche utilizzare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage. Se definisci sia ref che il corpo di questo elemento, il valore di ref viene applicato e ha la precedenza quando la variabile di flusso viene impostata nella richiesta. (Il contrario è vero quando la variabile identificata in ref non è impostata nella richiesta.) Ad esempio: <Rate ref="request.header.custom_rate">1pm</Rate> In questo esempio, se il client non passa un'intestazione custom_rate, la velocità per il proxy API è di 1 richiesta al minuto per tutti i client. Se il client passa un'intestazione custom_rate, il limite di frequenza diventa di 10 richieste al secondo per tutti i client sul proxy, finché non viene inviata una richiesta senza l'intestazione custom_rate. Puoi utilizzare <Identifier> per raggruppare le richieste e applicare tariffe personalizzate per diversi tipi di client. Se specifichi un valore per ref, ma non imposti la frequenza nel corpo dell'elemento <Rate> e il client non passa un valore, il criterio SpikeArrest genera un errore.	Facoltativo	n/a

La tabella seguente descrive gli attributi di Rate che definiscono il comportamento di limitazione del traffico:

Attributo	Descrizione
messagesPerPeriod	Specifica il numero di messaggi consentiti in un periodo definito. Ad esempio, se un criterio è configurato per "10ps" (10 al secondo), il valore di messagesPerPeriod sarà 10.
periodInMicroseconds	Definisce il periodo di tempo, in microsecondi, durante il quale viene calcolato messagesPerPeriod. Per una configurazione "10ps", questo valore sarebbe 1.000.000, che equivale a un secondo.
maxBurstMessageCount	Rappresenta il numero massimo di richieste che possono essere consentite immediatamente o in un breve burst all'inizio di un nuovo intervallo.

Nota:i valori e i calcoli di questi attributi possono essere influenzati dal numero di MP e dall'attivazione dell'impostazione UseEffectiveCount. Ad esempio, se imposti una tariffa di "10ps" con 10 MP e UseEffectiveCount è attivato, la tariffa effettiva per ogni MP è 1ps. Gli attributi interni del singolo MP vengono modificati di conseguenza. Ad esempio, l'attributo messagesPerPeriod potrebbe essere impostato su 1 e periodInMicroseconds su 1.000.000.

<UseEffectiveCount>

Questo elemento ti consente di scegliere tra algoritmi di eliminazione dei picchi distinti impostando il valore su true o false, come spiegato di seguito:

true

Se impostato su true, SpikeArrest viene distribuito in una regione. Ciò significa che i conteggi delle richieste vengono sincronizzati tra i processori di messaggi (MP) in una regione. Inoltre, viene utilizzato un algoritmo di limitazione di frequenza "a finestra scorrevole". Questo algoritmo fornisce un comportamento coerente del limite di frequenza e non "uniforma" il numero di richieste in entrata che possono essere inviate al backend. Se viene inviato un burst di richieste in un breve intervallo di tempo, queste sono consentite a condizione che non superino il limite di frequenza configurato, come impostato nell'elemento <Rate>. Ad esempio:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

false (impostazione predefinita)

Nota:anche se il valore predefinito è false, le organizzazioni Apigee devono impostare questo elemento su true.

Il livellamento della frequenza non è supportato per le organizzazioni Apigee.

Se impostato su false (valore predefinito), il criterio Spike Arrest utilizza un algoritmo "token bucket" che attenua i picchi di traffico dividendo il limite di frequenza specificato in intervalli più piccoli. Uno svantaggio di questo approccio è che più richieste legittime ricevute in un breve intervallo di tempo possono potenzialmente essere rifiutate.

Ad esempio, supponiamo che tu inserisca una frequenza di 30 pm (30 richieste al minuto). Durante i test, potresti pensare di poter inviare 30 richieste in 1 secondo, purché rientrino in un minuto. Tuttavia, non è così che la norma applica l'impostazione. Se ci pensi, 30 richieste in un periodo di 1 secondo potrebbero essere considerate un mini picco in alcuni ambienti.

• Le tariffe al minuto vengono uniformate in richieste complete consentite a intervalli di secondi.
  

  Ad esempio, 30pm viene uniformato in questo modo:
  60 secondi (1 minuto) / 30pm = intervalli di 2 secondi o 1 richiesta consentita ogni 2 secondi. Una seconda richiesta entro 2 secondi non andrà a buon fine. Inoltre, una 31ª richiesta entro un minuto non andrà a buon fine.

• Le tariffe al secondo vengono uniformate in richieste complete consentite a intervalli di millisecondi.

  Ad esempio, 10ps viene uniformato in questo modo:
  1000 millisecondi (1 secondo) / 10ps = intervalli di 100 millisecondi o 1 richiesta consentita ogni 100 millisecondi. Una seconda richiesta entro 100 ms non andrà a buon fine. Inoltre, l'undicesima richiesta entro un secondo non andrà a buon fine.

Nota:nel livellamento della frequenza, il numero di richieste è sempre un numero intero maggiore di zero. Il livellamento non prevede mai il calcolo di frazioni di richieste.

Valore predefinito	Falso
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<SpikeArrest>
Elementi secondari	Nessuno

La tabella seguente descrive gli attributi dell'elemento <UseEffectiveCount>:

Attributo	Descrizione	Predefinito	Presenza
ref	Identifica la variabile che contiene il valore di <UseEffectiveCount>. Può essere qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio. Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage.	n/a	Facoltativo

Variabili di flusso

Quando viene eseguito un criterio SpikeArrest, viene compilata la seguente variabile di flusso:

Variabile	Tipo	Autorizzazione	Descrizione
ratelimit.policy_name.failed	Booleano	Sola lettura	Indica se il criterio non è stato rispettato (true o false).

Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso.

Messaggi di errore

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

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
policies.ratelimit.FailedToResolveSpikeArrestRate	500	This error occurs if the reference to the variable containing the rate setting within the <Rate> element cannot be resolved to a value within the SpikeArrest policy. This element is mandatory and used to specify the spike arrest rate in the form of intpm or intps.
policies.ratelimit.InvalidMessageWeight	500	This error occurs if the value specified for the <MessageWeight> element through a flow variable is invalid (a non-integer value).
policies.ratelimit.SpikeArrestViolation	429	The rate limit is exceeded.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidAllowedRate	If the spike arrest rate specified in the <Rate> element of the SpikeArrest policy is not an integer or if the rate does not have ps or pm as a suffix, then the deployment of the API proxy fails.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	ratelimit.SA-SpikeArrestPolicy.failed = true

Example error response

Shown below is an example error response:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

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

Il codice di stato HTTP attuale per il superamento di un limite di frequenza impostato da una policy Quota o SpikeArrest è 429 (Troppe richieste).

Schemi

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Argomenti correlati

• Criteri per le quote: criteri per le quote, per limitare il traffico sui singoli client
• Limitazione di frequenza per una panoramica della limitazione di frequenza
• Confronto tra le norme relative alle quote e SpikeArrest