Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Il criterio di Arresto dei picchi 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à.
Elemento <SpikeArrest>
Definisce il criterio di Spike Arrest.
Valore predefinito | Vedi la scheda Criterio predefinito di seguito |
Obbligatorio? | Facoltativo |
Digitare | Oggetto complesso |
Elemento principale | n/d |
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>
Norma predefinita
L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio di arresto dei picchi al flusso nella UI Edge:
<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>true</UseEffectiveCount> </SpikeArrest>
Questo elemento ha i seguenti attributi comuni a tutti i criteri:
Attributo | Predefinita | Obbligatorio? | Description (Descrizione) |
---|---|---|---|
name |
N/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
false | Facoltativo | Imposta su "false" per restituire un errore quando un criterio non va a buon fine. Si tratta di un comportamento previsto per la maggior parte dei criteri. Impostalo su "true" per far sì che l'esecuzione del flusso continui anche dopo l'esito negativo di un criterio. |
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 |
false | Deprecazione | Questo attributo è obsoleto. |
Esempi
I seguenti esempi mostrano alcuni modi in cui è possibile utilizzare il criterio Arrest Spike:
Esempio 1
Nell'esempio seguente la frequenza è impostata su cinque al secondo:
<SpikeArrest name="Spike-Arrest-1"> <Rate>5ps</Rate> </SpikeArrest>
Il criterio agevola la frequenza a una richiesta consentita 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> </SpikeArrest>
Questo criterio di esempio agevola la frequenza a una richiesta consentita ogni cinque secondi (60/12).
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" /> </SpikeArrest>
Inoltre, l'elemento <MessageWeight>
accetta un valore personalizzato (l'intestazione weight
) che regola la ponderazione dei messaggi per app o client specifici. In questo modo
viene fornito un controllo aggiuntivo sulla limitazione per le entità identificate con l'elemento
<Identifier>
.
Esempio 4
L'esempio seguente indica a Spike Arrest di cercare un valore di runtime impostato tramite la richiesta trasmessa come variabile di flusso request.header.runtime_rate
:
<SpikeArrest name="Spike-Arrest-1"> <Rate ref="request.header.runtime_rate" /> </SpikeArrest>
Il valore della variabile di flusso deve essere intpm
o
intps
.
Per provare questo esempio, esegui una richiesta simile alla seguente:
curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'
Riferimento per l'elemento secondario
Questa sezione descrive 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 dal suono più naturale.
L'elemento <DisplayName>
è comune a tutti i criteri.
Valore predefinito | n/d |
Obbligatorio? | Campo facoltativo. Se ometti <DisplayName> , viene utilizzato il valore dell'attributo name del criterio |
Digitare | Stringa |
Elemento principale | <PolicyElement> |
Elementi secondari | Nessuno |
L'elemento <DisplayName>
utilizza la seguente sintassi:
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 di arresto dei picchi 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 ai fini del proprio tasso di arresto dei picchi e non di tutte le richieste al proxy.
Da utilizzare in combinazione con l'elemento <MessageWeight>
per avere 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/d |
Obbligatorio? | Facoltativo |
Digitare | 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 di arresto dei picchi in base all'ID sviluppatore:
<SpikeArrest name="Spike-Arrest-1"> <Identifier ref="developer.id"/> <Rate>42pm</Rate/> </SpikeArrest>
Nella tabella seguente vengono descritti gli attributi di <Identifier>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref |
Identifica la variabile con cui Spike Arrest raggruppa le richieste in entrata. Puoi utilizzare qualsiasi variabile di flusso per indicare un client univoco, ad esempio quelli disponibili con il criterio VerificationAPIKey. Puoi anche impostare variabili personalizzate tramite i criteri JavaScript o AssignMessage. | n/d | Obbligatorio |
Questo elemento è discusso anche nel seguente post della community di Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.
<MessageWeight>
Specifica la ponderazione definita per ciascun messaggio. Il peso del messaggio modifica l'impatto di una singola richiesta sul calcolo del tasso di arresto anomalo. Il peso del messaggio può essere qualsiasi variabile di flusso, come un'intestazione HTTP, un parametro di query, un parametro del modulo o il contenuto del corpo del messaggio. Puoi anche utilizzare le variabili personalizzate mediante i criteri JavaScript o AssignMessage.
Da utilizzare in combinazione con <Identifier>
per limitare ulteriormente le richieste da parte di client o app specifici.
Ad esempio, se l'arresto anomalo <Rate>
è 10pm
e un'app invia richieste con una ponderazione di 2
, allora sono consentiti solo cinque messaggi al minuto da quel client perché ogni richiesta viene conteggiata come 2.
Valore predefinito | n/d |
Obbligatorio? | Facoltativo |
Digitare | 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" /> </SpikeArrest>
In questo esempio, <MessageWeight>
accetta un valore personalizzato (l'intestazione weight
nella richiesta) che regola la ponderazione dei messaggi per client specifici. In questo modo
viene fornito un controllo aggiuntivo sulla limitazione per le entità identificate con l'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, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio. Per maggiori informazioni, consulta la documentazione di riferimento sulle variabili di flusso. Puoi anche impostare variabili personalizzate mediante i criteri JavaScript o AssignMessage. | Obbligatorio | N/A |
<Rate>
Specifica la frequenza con cui limitare i picchi (o i burst) di traffico impostando il numero di richieste consentite in intervalli al minuto o al secondo. Puoi anche utilizzare questo elemento in combinazione con <Identifier>
e <MessageWeight>
per limitare facilmente il traffico in fase di runtime accettando valori dal client.
Valore predefinito | n/d |
Obbligatorio? | Obbligatorio |
Digitare | Numero intero |
Elemento principale |
<SpikeArrest>
|
Elementi secondari | Nessuno |
Sintassi
Puoi specificare le tariffe in uno dei seguenti modi:
- Una tariffa statica da te specificata come corpo dell'elemento
<Rate>
. - Un valore della variabile che può essere trasmesso 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 delle tariffe validi (definiti come valore variabile o nel corpo dell'elemento) devono essere conformi al seguente formato:
intps
(numero di richieste al secondo, suddivise in intervalli di millisecondi)intpm
(numero di richieste al minuto, suddivise in intervalli di secondi)
Il valore di int deve essere un numero intero positivo, diverso da zero.
Esempio 1
Nell'esempio seguente la frequenza viene impostata su cinque richieste al secondo:
<SpikeArrest name="Spike-Arrest-1"> <Rate>5ps</Rate> </SpikeArrest>
Il criterio agevola 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> </SpikeArrest>
Questo criterio di esempio agevola la frequenza 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 velocità. Può essere qualsiasi variabile di flusso, come un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio, oppure un valore come un KVM. Per ulteriori informazioni, consulta la documentazione di riferimento sulle variabili di flusso.
Puoi anche utilizzare le variabili personalizzate mediante i criteri JavaScript o AssignMessage. Se definisci sia Ad esempio: <Rate ref="request.header.custom_rate">1pm</Rate> In questo esempio, se il client non passa un'intestazione "custom_rate", la tariffa per il proxy API è di una 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 Se specifichi un valore per |
Facoltativo | n/d |
<UseEffectiveCount>
Distribuisce il numero di Spike Arrest tra i processori di messaggi (MP) quando utilizzi i gruppi a scalabilità automatica.
Sintassi
<SpikeArrest continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <UseEffectiveCount>[false|true]</UseEffectiveCount> </SpikeArrest>
Esempio 1
L'esempio seguente imposta <UseEffectiveCount>
su true:
<SpikeArrest name='Spike-Arrest-1'> <Rate>40ps</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
L'elemento <UseEffectiveCount>
è facoltativo. Il valore predefinito è false
quando l'elemento viene omesso dal criterio Spike Arrest.
Valore predefinito | falso |
Obbligatorio? | Facoltativo |
Digitare | Booleano |
Elemento principale |
<SpikeArrest>
|
Elementi secondari | Nessuno |
La tabella seguente descrive gli attributi dell'elemento <UseEffectiveCount>
:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref |
Identifica la variabile contenente 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 documentazione di riferimento sulle variabili di flusso. Puoi anche impostare variabili personalizzate
mediante i criteri JavaScript o AssignMessage. |
n/d | Facoltativo |
L'effetto di <UseEffectiveCount>
dipende dal suo valore:
true
: il limite di frequenza dei picchi di un MP è pari a<Rate>
diviso per il numero attuale di MP nello stesso pod. Il limite aggregato è il valore di<Rate>
. Quando i MP vengono aggiunti (o rimossi in modo dinamico), i limiti di frequenza dei picchi individuali aumentano (o diminuiscono), ma il limite aggregato rimane invariato.false
(questo è il valore predefinito se omesso): il limite di frequenza di picco di ogni MP è semplicemente il valore del relativo<Rate>
. Il limite aggregato è la somma delle tariffe di tutti i MP. Quando vengono aggiunti o rimossi MP, i limiti di frequenza dei picchi individuali rimangono invariati, ma il limite aggregato aumenta (o diminuisce).
La tabella seguente mostra l'effetto di <UseEffectiveCount>
sul limite di frequenza effettivo di
ogni MP:
Valore di <UseEffectiveCount> |
||||||
---|---|---|---|---|---|---|
false |
false |
false |
true |
true |
true |
|
N. di MP | 8 | 4 | 2 | 8 | 4 | 2 |
Valore di <Rate> |
10 | 10 | 10 | 40 | 40 | 40 |
Tariffa effettiva per MP | 10 | 10 | 10 | 5 | 10 | 20 |
Limite aggregato | 80 | 40 | 20 | 40* | 40* | 40* |
* Uguale a <Rate> . |
In questo esempio, nota che quando il numero di MP viene ridotto da 4 a 2 e
<UseEffectiveCount>
è false
, la tariffa effettiva per MP rimane invariata (a
10). Ma quando <UseEffectiveCount>
è true
, la tariffa effettiva per MP va da
10 a 20 quando il numero di MP viene ridotto da 4 a 2.
Variabili di flusso
Quando viene eseguito un criterio di arresto dei picchi, 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 ulteriori informazioni, consulta la documentazione di riferimento sulle variabili di flusso.
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge 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
all'interno dell'elemento <Rate> non può essere risolto in un valore all'interno del criterio di
arresto dei picchi. 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 il tasso di arresto dei picchi specificato nell'elemento <Rate> del criterio di arresto dei picchi 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 di quota o arresto anomalo è 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à organizzazione.
Ad esempio:
curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property> . . . </Properties> </Organization>"
Schema
Ogni tipo di criterio è definito da uno schema XML (.xsd
). Come riferimento, gli schemi dei criteri sono disponibili su GitHub.
Argomenti correlati
- Criteri per le quote: criteri per le quote, per limitare il traffico su singoli client
- Limitazione di frequenza per una panoramica della limitazione di frequenza
- Confronto dei criteri di quota e SpikeArrest
- Esempi funzionanti di proxy API