Criterio SpikeArrest

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

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

Elemento <SpikeArrest>

Definisce il criterio SpikeArrest.

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

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

Esempi

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

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

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

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

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SpikeArrest>.

<DisplayName>

Utilizza questo attributo 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.

L'elemento <DisplayName> utilizza la seguente sintassi:

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

<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 ciascun sviluppatore verranno conteggiate ai fini del proprio tasso di Spike Arrest 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.

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

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

La tabella seguente descrive gli attributi di <Identifier>:

Questo elemento è trattato anche nel seguente post della community Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

Specifica la ponderazione definita per ogni messaggio. Il peso del messaggio modifica l'impatto di una singola richiesta sul calcolo del tasso di Spike Arrest. 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 in base a client o app specifici.

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

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

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

La tabella seguente descrive gli attributi di <MessageWeight>:

<Rate>

Specifica la velocità con cui limitare i picchi (o i burst) di traffico impostando il numero di richieste consentite a intervalli di minuti o secondi. Puoi utilizzare questo elemento anche in combinazione con <Identifier> e <MessageWeight> per limitare il traffico in modo fluido in fase di runtime accettando i valori del client.

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

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

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

La tabella seguente descrive gli attributi di <Rate>:

<Rate ref="request.header.custom_rate">1pm</Rate>

<UseEffectiveCount>

Distribuisce i conteggi di Spike Arrest tra i processori di messaggi (MP) quando vengono utilizzati gruppi di scalabilità automatica.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<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 dalla policy Spike Arrest.

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

L'effetto di <UseEffectiveCount> dipende dal suo valore:

• true: il limite di picco di un MP è il <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 individuali aumentano (o diminuiscono), ma il limite aggregato rimane invariato.
• false: Il limite del tasso 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 individuali del tasso di picco rimarranno invariati, ma il limite aggregato aumenterà (o diminuirà).

Il criterio SpikeArrest 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 essere potenzialmente rifiutate.

Ad esempio, supponiamo che tu inserisca una frequenza di 30 pm (30 richieste al minuto). Durante il 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.

La tabella seguente mostra l'effetto di <UseEffectiveCount> sul limite di frequenza effettivo di ogni MP:

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). Tuttavia, quando <UseEffectiveCount> è true, la tariffa effettiva per MP passa da 10 a 20 quando il numero di MP viene ridotto da 4 a 2.

Variabili di flusso

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

Per ulteriori informazioni, consulta 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 Edge 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.

Deployment errors

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

Fault variables

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

Example error response

Shown below is an example error response:

{  
   "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 quota o da un criterio Spike Arrest è 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://api.enterprise.apigee.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

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 a quote e SpikeArrest
• Esempi funzionanti di proxy API