Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza documentazione di Apigee Edge.
Il criterio SpikeArrest protegge dai picchi di traffico con l'elemento <Rate>
. Questo
limita il numero di richieste elaborate da un proxy API e inviate a un backend,
per una protezione contro tempi di inattività e ritardi delle prestazioni.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per 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 a cui un'app client è autorizzata vengono inviate a un'API nel corso di un'ora, un giorno, una settimana o un mese. I criteri per le quote applicano di consumo massimo nelle app client mantenendo un contatore distribuito che rilevi i limiti richieste.
Utilizza Quota per applicare contratti aziendali o SLA con sviluppatori e partner anziché che per la gestione operativa del traffico. Utilizza SpikeArrest per la protezione da picchi improvvisi nell'API per via del traffico. Consulta anche la sezione Confronto Criteri per quote e SpikeArrest.
Video
Questi video illustrano i casi d'uso di queste norme:
A cosa serve
Confronta criteri per le quote
<SpikeArrest>
elemento
Definisce il criterio SpikeArrest.
Valore predefinito | Consulta la scheda Criterio predefinito di seguito |
Obbligatorio? | Facoltativo |
Tipo | Complesso oggetto |
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>
Criterio predefinito
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/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel 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 | Deprecato | Questo attributo è stato ritirato. |
Esempi
I seguenti esempi mostrano alcuni modi in cui è possibile 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 il perfezionamento, viene applicato come di una richiesta per ogni intervallo di 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 alla frequenza una richiesta per intervallo di 5 secondi (60/12). Se in un pod ci sono di una richiesta in un intervallo di 5 secondi, come le richieste (nessun smoothing) a condizione che il numero di richieste sia inferiore a quello 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 (il
weight
) che regola le ponderazioni dei messaggi per app o client specifici. Questo
fornisce un ulteriore controllo sulla limitazione per le entità identificate con
Elemento <Identifier>
.
Esempio 4
L'esempio seguente indica a SpikeArrest di cercare un valore di runtime impostato tramite il metodo
richiesta trasmessa 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
oppure
intps
.
Per provare questo esempio, esegui una richiesta come la seguente:
curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'
Riferimento elemento secondario
In questa sezione vengono descritti gli elementi secondari di <SpikeArrest>
.
<DisplayName>
Utilizzalo in aggiunta 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/A |
Obbligatorio? | Facoltativo. Se ometti <DisplayName> , viene utilizzato il valore dell'attributo name del criterio. |
Tipo | Stringa |
Elemento principale | <PolicyElement> |
Elementi secondari | Nessuna esperienza |
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 il criterio SpikeArrest possa essere applicato in base sul cliente. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, nel qual caso ogni le richieste degli sviluppatori verranno conteggiate ai fini del loro tasso di SpikeArrest e non di tutte le richieste al proxy.
Da utilizzare insieme all'elemento <MessageWeight>
per avere un'impostazione più granulare
sulla limitazione delle richieste.
Se lasci vuoto l'elemento <Identifier>
, viene applicato un limite di frequenza per tutte le richieste
in quel 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
Nell'esempio seguente viene applicato il criterio SpikeArrest per ogni ID sviluppatore:
<SpikeArrest name="Spike-Arrest-1"> <Identifier ref="developer.id"/> <Rate>42pm</Rate/> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
Nella tabella seguente vengono descritti 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 unico, come quelli disponibili con CriterioVerifyAPIKey. Puoi anche impostare variabili personalizzate utilizzando Il criterio JavaScript o il criterioAssignMessage | n/a | Obbligatorio |
Questo elemento è discusso 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 del tasso di SpikeArrest. Il peso del messaggio può essere qualsiasi 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 variabili personalizzate usando il criterio JavaScript o il metodo CriterioAssignMessage:
Da utilizzare insieme a <Identifier>
per limitare ulteriormente le richieste del
per client o app specifici.
Ad esempio, se SpikeArrest <Rate>
è 10pm
e un'app invia
richieste con una ponderazione di 2
, allora sono consentiti solo cinque messaggi al minuto da
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 (il valore weight
l'intestazione nella richiesta) che regola le ponderazioni dei messaggi per client specifici. Questo
fornisce un ulteriore controllo sulla limitazione per le entità identificate con
Elemento <Identifier>
.
Nella tabella seguente vengono descritti 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, come parametro di query HTTP, intestazione o contenuto del corpo del messaggio. Per ulteriori informazioni, vedi Riferimento per le variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterioAssignMessage | Obbligatorio | N/D |
<Rate>
Specifica la frequenza con cui limitare i picchi di traffico (o burst) impostando il numero di
richieste consentite in intervalli al minuto o al secondo. Puoi utilizzare questo elemento anche
in abbinamento con <Identifier>
e <MessageWeight>
per
limitare in modo fluido il traffico in fase di runtime accettando valori dal client. Utilizza la
Elemento <UseEffectiveCount>
per impostare l'algoritmo di limitazione di frequenza utilizzato dal criterio.
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 frequenza statica specificata come corpo dell'elemento
<Rate>
- Un valore variabile, che può essere passato dal cliente. identificare
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 delle tariffe validi (definiti come valore variabile o nel corpo dell'elemento) devono saranno conformi al seguente formato:
intps
(numero di richieste al secondo, semplificate in intervalli di millisecondi)intpm
(numero di richieste al minuto, semplificate 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 riduce 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 attenua la tariffa a una richiesta consentita ogni cinque secondi (60/12).
Nella tabella seguente vengono descritti gli attributi di <Rate>
:
Attributo | Descrizione | Presenza | Predefinito |
---|---|---|---|
ref |
Identifica una variabile di flusso che specifica la frequenza. Può essere qualsiasi flusso
quali un parametro di query HTTP, un'intestazione, i contenuti del corpo del messaggio o un valore
come una KVM. Per saperne di più, consulta Riferimento per le variabili di flusso.
Puoi anche usare le variabili personalizzate utilizzando il criterio JavaScript o il criterioAssignMessage 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 diversi algoritmi di arresto dei picchi impostando il valore
su true
o false
, come spiegato di seguito:
true
Se impostato su true
, SpikeArrest viene distribuito in una regione. Ciò significa
i conteggi delle richieste vengono sincronizzati tra i processori dei messaggi (MP) di una regione. Inoltre, una "finestra scorrevole"
viene impiegato un algoritmo di limitazione di frequenza. Questo
l'algoritmo fornisce un comportamento coerente della limitazione di frequenza e non "attenua" il numero di in entrata
richieste che possono essere inviate al backend. Se viene inviata una serie di richieste
in un breve intervallo di tempo,
sono consentiti purché non superino
limite di frequenza, 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 viene impostato su false
(valore predefinito),
il criterio SpikeArrest utilizza un "bucket 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 ricevute in un breve lasso di tempo
possono essere potenzialmente rifiutati.
Ad esempio, supponi di inserire una frequenza di 30:00 (30 richieste al minuto). Durante i test, potresti Pensi che potresti inviare 30 richieste in un secondo, purché vengano ricevute entro un minuto. Ma questo è non il modo in cui il criterio applica l'impostazione. A pensarci bene, 30 richieste entro un secondo periodo potrebbe essere considerato un piccolo picco in alcuni ambienti.
- Le tariffe al minuto vengono semplificate nelle richieste complete consentite a intervalli
di secondi.
Ad esempio, le ore 30:00 vengono semplificate in questo modo:
60 secondi (1 minuto) / 30:00 = intervalli di 2 secondi o 1 richiesta consentita ogni 2 secondi. R una seconda richiesta entro 2 secondi non andrà a buon fine. Inoltre, una 31a richiesta entro un minuto errore. - Le tariffe al secondo vengono semplificate nelle richieste complete consentite a intervalli
di millisecondi.
Ad esempio, 10 ps viene rettificato in questo modo:
1000 millisecondi (1 secondo) / 10 ps = intervalli di 100 millisecondi o 1 richiesta consentita ogni 100 millisecondi. Una seconda richiesta entro 100 ms avrà esito negativo. Inoltre, un'undicesima richiesta entro un secondo non riuscirà.
Valore predefinito | Falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<SpikeArrest>
|
Elementi secondari | Nessuno |
Nella tabella seguente vengono descritti 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 di un messaggio. Per maggiori informazioni
informazioni, consulta Riferimento per le variabili di flusso. Puoi anche impostare variabili personalizzate
utilizzando il criterio JavaScript o il criterioAssignMessage |
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 è riuscito (true o
false ). |
Per saperne di più, consulta Riferimento per le variabili di flusso.
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Correggi |
---|---|---|---|
policies.ratelimit.FailedToResolveSpikeArrestRate |
500 |
Questo errore si verifica se il riferimento alla variabile contenente l'impostazione della tariffa nell'elemento <Rate> non può essere risolto in un valore all'interno del criterio SpikeArrest . Questo elemento è obbligatorio e utilizzato per specificare il tasso di arresto dei picchi di traffico
nel formato 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 errore | Causa | Correggi |
---|---|---|
InvalidAllowedRate |
Se la percentuale di arresto dei 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice di 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
in false
utilizzando l'API Aggiorna le 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 criterio è definito da uno schema XML (.xsd
). Come riferimento, consulta gli schemi dei criteri
sono disponibili su GitHub.
Argomenti correlati
- Criteri per le quote: quota per limitare il traffico su singoli client
- Limitazione di frequenza per una limitazione di frequenza panoramica
- Confronto Criteri di quote e SpikeArrest