Norme di 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, in modo da proteggere da ritardi delle prestazioni e tempi di inattività.

Questo è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ogni 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 nel corso di un'ora, un giorno, una settimana o un mese. I criteri per le quote applicano limiti di consumo sulle app client gestendo un contatore distribuito che rileva le richieste in entrata.

Utilizza Quota per applicare contratti commerciali o SLA (accordi sul livello del servizio) con sviluppatori e partner, anziché per la gestione operativa del traffico. Utilizza SpikeArrest per proteggerti da picchi improvvisi nel traffico delle API. Vedi anche Confronto dei criteri di Quota e SpikeArrest.

Video

Questi video trattano casi d'uso relativi a questa norma:

Perché è necessario

Confronta criteri per le quote

<SpikeArrest> elemento

Definisce il criterio SpikeArrest.

Valore predefinito	Consulta la scheda Criterio predefinito di seguito
Obbligatorio?	Facoltativo
Tipo	Oggetto complesso
Elemento principale	n/d
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 flusso nella UI:

<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 name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, 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 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: Le regole di errore vengono attivate SOLO in uno stato di errore (su continueOnError) Gestione degli errori nel 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	Deprecato	Questo attributo è stato ritirato.

Esempi

I seguenti esempi mostrano alcuni modi in cui puoi utilizzare il criterio SpikeArrest:

Esempio 1

Nell'esempio seguente la frequenza viene impostata su cinque al secondo:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Questo criterio di esempio consente un massimo di cinque richieste al secondo. Mediante il smoothing, viene applicato come un massimo di una richiesta per ogni intervallo di 200 millisecondi (1000/5).

Esempio 2

Nell'esempio seguente la frequenza viene impostata 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 di una richiesta per intervallo di 5 secondi (60/12). Se è presente più di una richiesta nell'intervallo di 5 secondi, queste sono consentite (senza livellamento), purché 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 (l'intestazione weight) che regola la ponderazione 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="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'

Suggerimento: dai un'occhiata a Come posso utilizzare i prodotti API per impostare i limiti di arresto dei picchi? che spiega come impostare la percentuale di SpikeArrest utilizzando variabili personalizzate impostate in un prodotto API.

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 al client. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, nel qual caso le richieste di ogni sviluppatore verranno conteggiate ai fini del rispettivo tasso di SpikeArrest e non per 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 in quel proxy API.

Valore predefinito	n/d
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<SpikeArrest>
Elementi secondari	Nessun valore

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 con cui SpikeArrest raggruppa le richieste in entrata. Puoi utilizzare qualsiasi variabile di flusso per indicare un client univoco, come quelli disponibili con il criterio VerificationAPIKey. Puoi anche impostare variabili personalizzate utilizzando le norme relative a JavaScript o il criterioAssignMessage.	n/d	Obbligatorio

Questo elemento è discusso anche in questo post della community di Apigee.

<MessageWeight>

Specifica la ponderazione definita per ciascun messaggio. Il peso del messaggio modifica l'impatto di una singola richiesta sul calcolo della percentuale di SpikeArrest. Il peso del messaggio può essere qualsiasi variabile di flusso, ad esempio un'intestazione HTTP, un parametro di query, un parametro modulo o un contenuto del corpo del messaggio. Puoi anche utilizzare le variabili personalizzate tramite le norme relative a JavaScript o il criterioAssignMessage.

Da utilizzare in combinazione con <Identifier> per limitare ulteriormente le richieste da parte di client o app specifici.

Ad esempio, se lo SpikeArrest <Rate> è 10pm e un'app invia richieste con una ponderazione di 2, allora saranno consentiti solo cinque messaggi al minuto da quel client perché ogni richiesta viene conteggiata come 2.

Valore predefinito	n/d
Obbligatorio?	Facoltativo
Tipo	Numero intero
Elemento principale	<SpikeArrest>
Elementi secondari	Nessun valore

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 della richiesta) che regola le ponderazioni dei messaggi per client 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 un contenuto del corpo del messaggio. Per maggiori informazioni, consulta Riferimento alle variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando le norme relative a JavaScript o il criterioAssignMessage.	Obbligatorio	N/A

<Rate>

Specifica la frequenza con cui limitare i picchi di traffico (o i burst) 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. Utilizza l'elemento <UseEffectiveCount> per impostare l'algoritmo di limitazione della frequenza utilizzato dal criterio.

Nota: consulta la sezione SpikeArrest della pagina Limiti per conoscere i limiti di frequenza massimi che puoi specificare.

Valore predefinito	n/d
Obbligatorio?	Obbligatorio
Tipo	Numero intero
Elemento principale	<SpikeArrest>
Elementi secondari	Nessun valore

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

Nell'esempio seguente la frequenza viene impostata su cinque richieste al secondo:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

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

Esempio 2

Nell'esempio seguente la frequenza viene impostata su 12 richieste al minuto:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Questo criterio di esempio agevola 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 velocità. 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 un KVM. Per ulteriori informazioni, consulta la documentazione di riferimento sulle variabili di flusso. Puoi anche utilizzare le variabili personalizzate utilizzando le norme relative a JavaScript o il criterioAssignMessage. Se definisci sia ref sia il corpo di questo elemento, viene applicato il valore di ref 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 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 <Identifier> per raggruppare le richieste e applicare tariffe personalizzate per diversi tipi di client. Se specifichi un valore per ref ma non imposti la tariffa nel corpo dell'elemento <Rate> e il client non passa un valore, il criterio SpikeArrest genera un errore.	Facoltativo	n/d

<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 è distribuito in una regione. Ciò significa che il numero delle richieste viene sincronizzato 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 per la limitazione di frequenza e non "regola" il numero di richieste in entrata che possono essere inviate al backend. Se vengono inviate richieste di burst in un breve intervallo di tempo, sono consentite a condizione che non superino il limite di frequenza configurato 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)

Se è impostato su false (valore predefinito), il criterio SpikeArrest utilizza un algoritmo "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 intervallo di tempo potrebbero potenzialmente essere rifiutate.

Ad esempio, supponi di inserire una frequenza di 30 (30 richieste al minuto). Durante i test, potresti pensare di poter inviare 30 richieste in un secondo, purché vengano inviate entro un minuto. Ma non è questo il modo in cui il criterio applica l'impostazione. 30 richieste in un periodo di 1 secondo potrebbero essere considerate un mini picco in alcuni ambienti.

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

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

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

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

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

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

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ò trattarsi di qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o un contenuto del corpo del messaggio. Per ulteriori informazioni, consulta la documentazione di riferimento sulle variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando le norme relative a JavaScript o il criterioAssignMessage.	n/d	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 negativo (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 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.

Suggerimento: hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correggi per informazioni dettagliate sulla risoluzione dei problemi.

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

Suggerimento: hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correggi per avere informazioni dettagliate sulla risoluzione dei problemi.

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.

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:

Nota: per la gestione degli errori, la best practice consiste nell'eseguire il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{  
   "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 superare 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à organizzazione.

Attenzione: quando aggiorni le proprietà, devi passare all'API tutte le proprietà esistenti, anche se non vengono modificate. Se lasci le proprietà fuori dal payload per la chiamata API Aggiorna proprietà dell'organizzazione, le proprietà vengono rimosse. Per ottenere l'elenco corrente delle proprietà per l'ambiente, utilizza l'API Get Organization.

Se tenti di impostare una proprietà, ma il valore aggiornato della proprietà non viene restituito nel payload di risposta, significa che la proprietà deve essere impostata da un utente con il ruolo sysadmin. Contatta l'Assistenza Apigee per modificare il valore di una proprietà che richiede il ruolo sysadmin.

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

Schema

Ogni tipo di criterio è definito da uno schema XML (.xsd). Per riferimento, gli schemi dei criteri 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 dei criteri di Quota e SpikeArrest