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 da tempi di riposo.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.
La 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. Il criterio per le quote applica limiti di consumo alle app client mantenendo un contatore distribuito che conteggia le richieste in entrata.
Utilizza la quota per applicare contratti aziendali o SLA con sviluppatori e partner, anziché per la gestione del traffico operativo. Utilizza SpikeArrest per proteggerti da picchi improvvisi nel traffico delle API. Consulta anche Confronto tra i criteri Quota e SpikeArrest.
Video
Questi video illustrano i casi d'uso di queste norme:
Perché è utile
Confrontare i criteri per le quote
Elemento <SpikeArrest>
Definisce il criterio SpikeArrest.
Valore predefinito | Consulta la scheda Criterio predefinito di seguito |
Obbligatorio? | Facoltativo |
Tipo | Oggetto complesso |
Elemento principale | n/a |
Elementi secondari |
<Identifier> <MessageWeight> <Rate> (obbligatorio)<UseEffectiveCount> |
Sintassi
La sintassi dell'elemento <SpikeArrest>
è la seguente:
<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 un criterio 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 Se vuoi, utilizza l'elemento |
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:
|
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 riportati di seguito mostrano alcuni dei modi in cui puoi utilizzare il criterio SpikeArrest:
Esempio 1
L'esempio seguente imposta la frequenza su cinque al secondo:
<SpikeArrest name="Spike-Arrest-1"> <Rate>5ps</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>
Questo criterio di esempio consente un massimo di 5 richieste al secondo. Tramite l'appiattimento, viene applicato un massimo di una richiesta ogni 200 millisecondi (1000/5).
Esempio 2
L'esempio seguente imposta la frequenza su 12 al minuto:
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
Questo criterio di esempio consente un massimo di 12 richieste al minuto con una frequenza di una richiesta ogni 5 secondi (60/12). Se sono presenti più richieste nell'intervallo di 5 secondi, queste richieste sono consentite (nessun'appiattimento) 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 o 60/12):
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <Identifier ref="client_id" /> <MessageWeight ref="request.header.weight" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
Inoltre, l'elemento <MessageWeight>
accetta un valore personalizzato (la
intestazione weight
) che regola i pesi dei messaggi per app o client specifici. Ciò
offre un maggiore controllo 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 che viene passata come variabile di flusso request.header.runtime_rate
:
<SpikeArrest name="Spike-Arrest-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'
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>
Ti consente di scegliere come raggruppare le richieste in modo che il criterio SpikeArrest possa essere applicato in base al client. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, in questo caso le richieste di ogni sviluppatore verranno conteggiate per il relativo tasso di arresti anomali e non per tutte le richieste al proxy.
Da utilizzare in combinazione con l'elemento <MessageWeight>
per un controllo più granulare sulla limitazione delle richieste.
Se lasci vuoto l'elemento <Identifier>
, viene applicato un limite di frequenza per tutte le richieste al 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 cliente univoco, ad esempio quelle disponibili con la policy VerifyAPIKey. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio Assegna messaggio. | n/a | Obbligatorio |
Questo elemento è discusso anche in questo post della community di Apigee.
<MessageWeight>
Specifica la ponderazione definita per ogni messaggio. Il peso del messaggio modifica l'impatto di una singola richiesta sul calcolo del tasso di arresto picco. Il peso del messaggio può essere qualsiasi variabile di flusso, ad esempio un'intestazione HTTP, un parametro di query, un parametro di modulo o i contenuti del corpo del messaggio. Puoi anche utilizzare le variabili personalizzate utilizzando il criterio JavaScript o il criterio Assegna messaggio.
Da utilizzare in combinazione con <Identifier>
per limitare ulteriormente le richieste da client o app specifici.
Ad esempio, se SpikeArrest <Rate>
è 10pm
e un'app invia richieste con un peso di 2
, da quel client sono consentiti solo cinque messaggi al minuto perché ogni richiesta viene conteggiata 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 o 60/12):
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <Identifier ref="client_id" /> <MessageWeight ref="request.header.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 client specifici. Ciò
offre un maggiore controllo 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ò essere qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o i contenuti 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 Assegna messaggio. | Obbligatorio | N/D |
<Rate>
Specifica la frequenza con cui limitare i picchi (o le esplosioni) di traffico impostando il numero di richieste consentite in intervalli di un minuto o un secondo. Puoi anche utilizzare questo elemento insieme a <Identifier>
e <MessageWeight>
per limitare gradualmente il traffico in fase di esecuzione accettando i valori dal client. Utilizza l'elemento
<UseEffectiveCount>
per impostare l'algoritmo di limitazione della frequenza utilizzato dal criterio.
Consulta la sezione SpikeArrest della pagina Limiti per conoscere i limiti di frequenza massima 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 fissa specificata come corpo dell'elemento
<Rate>
- Un valore variabile che può essere passato dal client. Identifica il nome della variabile del 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 tariffa validi (definiti come valore di una variabile o nel corpo dell'elemento) devono essere conformi al 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="Spike-Arrest-1"> <Rate>5ps</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>
Il criterio appiana la frequenza a una richiesta consentita ogni 200 millisecondi (1000/5).
Esempio 2
L'esempio seguente imposta la frequenza su 12 richieste al minuto:
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
Questo criterio di esempio riduce 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ò essere qualsiasi variabile
del flusso, ad esempio un parametro di query HTTP, un'intestazione o i contenuti del corpo del messaggio oppure un valore
come un KVM. Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso.
Puoi anche utilizzare le variabili personalizzate utilizzando il criterio JavaScript o il criterio Assegna messaggio. Se definisci sia Ad esempio: <Rate ref="request.header.custom_rate">1pm</Rate> In questo esempio, se il client non passa un'intestazione Puoi utilizzare Se specifichi un valore per |
Facoltativo | n/a |
<UseEffectiveCount>
Questo elemento ti consente di scegliere tra algoritmi di arresto degli 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 con "finestra scorrevole". Questo
algoritmo fornisce un comportamento coerente del limite di frequenza e non "appiana" il numero di richieste
in entrata che possono essere inviate al backend. Se viene inviata una raffica di richieste in un breve intervallo di tempo,
queste sono consentite purché 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 (valore predefinito)
Se impostato su false
(il valore predefinito),
il criterio SpikeArrest utilizza un algoritmo "bucket di token" 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 inviate in un breve intervallo di tempo possono essere potenzialmente rifiutate.
Ad esempio, supponiamo che tu inserisca una frequenza di 30 richieste al minuto. Durante i test, potresti pensare di poter inviare 30 richieste in 1 secondo, purché vengano inviate entro un minuto. Tuttavia, non è così che il criterio 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 appiattite in richieste complete consentite a intervalli di secondi.
Ad esempio, 30 secondi vengono appiattiti come segue:
60 secondi (1 minuto) / 30 secondi = intervalli di 2 secondi o 1 richiesta consentita ogni 2 secondi. Una seconda richiesta effettuata entro 2 secondi non andrà a buon fine. Inoltre, una 31a richiesta effettuata entro un minuto non andrà a buon fine. - Le tariffe al secondo vengono appiattite in richieste complete consentite in intervalli di millisecondi.
Ad esempio, 10 pps viene appiattito come segue:
1000 millisecondi (1 secondo) / 10 pps = intervalli di 100 millisecondi o 1 richiesta consentita ogni 100 millisecondi. Una seconda richiesta entro 100 ms non andrà a buon fine. Inoltre, un'11a richiesta entro un secondo non andrà a buon fine.
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 i contenuti 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 Assegna messaggio. |
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 ha avuto esito positivo o meno (true o
false ). |
Per ulteriori informazioni, consulta la sezione 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 Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice guasto | Stato HTTP | Causa | Correggi |
---|---|---|---|
policies.ratelimit.FailedToResolveSpikeArrestRate |
500 |
Questo errore si verifica se il riferimento alla variabile contenente l'impostazione della tariffa
all'interno dell'elemento <Rate> non può essere risolto in un valore all'interno del criterio SpikeArrest . Questo elemento è obbligatorio e viene utilizzato per specificare il tasso di arresto degli picchi sotto forma di intpm o intps . |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
Questo errore si verifica se il valore specificato per l'elemento <MessageWeight> tramite una variabile di flusso non è valido (un valore non intero). |
build |
policies.ratelimit.SpikeArrestViolation |
429 |
Il limite di frequenza è stato superato. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome dell'errore | Causa | Correggi |
---|---|---|
InvalidAllowedRate |
Se la frequenza di arresto degli picchi specificata nell'elemento <Rate> del criterio SpikeArrest
non è un numero intero o se la frequenza non ha ps o pm come suffisso,
il deployment del proxy API non va a buon fine. |
build |
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. | fault.name Matches "SpikeArrestViolation" |
ratelimit.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | ratelimit.SA-SpikeArrestPolicy.failed = true |
Esempio di risposta di errore
Di seguito è riportato un esempio di risposta di errore:
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.SpikeArrestViolation" }, "faultstring":"Spike arrest violation. Allowed rate : 10ps" } }
Esempio di regola di errore
Di seguito è riportato un esempio di regola di errore per gestire un errore SpikeArrestViolation
:
<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>
L'attuale codice di stato HTTP per il superamento di un limite di frequenza impostato da un criterio Quota o SpikeArrest è 429 (Troppe richieste).
Per modificare il codice di stato HTTP in 500 (errore interno del server), imposta la proprietà features.isHTTPStatusTooManyRequestEnabled
su false
utilizzando l'API Aggiorna proprietà dell'organizzazione.
Ad esempio:
curl -u email:password -X POST -H "Content-type:application/xml" http://apigee.googleapis.com/v1/organizations/myorg -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property> . . . </Properties> </Organization>"
Schemi
Ogni tipo di norma è definito da uno schema XML (.xsd
). Come riferimento, gli schemi delle norme 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 i criteri Quota e SpikeArrest