Criterio 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, proteggendo da ritardi nelle prestazioni e tempi di inattività.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ciascun tipo di ambiente, consulta Tipi di criteri.

Differenza tra SpikeArrest e Quota

I criteri per le quote configurano 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 alle app client mantenendo un contatore distribuito che conteggia le richieste in entrata.

Utilizza Quota per applicare contratti commerciali o SLA con sviluppatori e partner, piuttosto che per la gestione del traffico operativo. Utilizza SpikeArrest per proteggerti da picchi improvvisi di traffico API. Vedi anche Confronto tra le norme Quota e SpikeArrest.

Video

Questi video illustrano i casi d'uso di questa norma:

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>false</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="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

curl https://my-api-endpoint.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.

La sintassi dell'elemento <DisplayName> è la seguente:

<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 a un elemento della richiesta in entrata. Ad esempio, puoi applicare limiti di frequenza per ID sviluppatore, nel qual caso tutte le richieste inviate dalle app di proprietà di un determinato sviluppatore condivideranno un unico conteggio SpikeArrest. In alternativa, puoi applicare un limite di frequenza per ID client, nel qual caso ogni app client sarà soggetta a un contatore del limite di frequenza distinto. Puoi anche fare riferimento a una variabile impostata in precedenza dal proxy. Questa variabile potrebbe combinare più fattori, ad esempio l'ID client e l'indirizzo IP del client.

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 al 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/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

La tabella seguente descrive gli attributi di <Identifier>:

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

<MessageWeight>

Specifica la ponderazione definita per il messaggio corrente. 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 del modulo o il contenuto del corpo del messaggio. Tuttavia, in genere non utilizzeresti una variabile derivata direttamente dalla richiesta in entrata. In alternativa, puoi utilizzare una variabile che rappresenta un attributo personalizzato in un prodotto API o nell'applicazione client. Puoi anche utilizzare variabili personalizzate impostate con valori dinamici tramite il JavaScript policy o il AssignMessage policy. In tutti i casi, il valore deve essere un numero intero positivo diverso da zero.

Utilizza il peso insieme a <Identifier> per limitare ulteriormente le richieste di client o app specifici.

Ad esempio, se SpikeArrest <Rate> è 10pm e il proxy utilizza una variabile che contiene il valore 2 per il peso del messaggio, verranno consentiti solo 5 messaggi al minuto per l'identificatore specificato perché ogni richiesta conta come 2.

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

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Default-Weight-1">
  <Rate>1000pm</Rate>
  <Identifier ref="client_id" />
  <!-- omit <MessageWeight/> to use a default weight of 1 -->
  <UseEffectiveCount>true</UseEffectiveCount>
</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 un minuto o di un secondo. Puoi utilizzare questo elemento in combinazione con <Identifier> e <MessageWeight> per limitare il traffico in modo uniforme in fase di runtime con un controllo preciso. Utilizza l'elemento <UseEffectiveCount> per impostare l'algoritmo di limitazione della frequenza utilizzato dalla policy.

Consulta la sezione SpikeArrest della pagina Limiti per i limiti di frequenza massimi che puoi specificare.

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

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

La tabella seguente descrive gli attributi di <Rate>:

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

<UseEffectiveCount>

Questo elemento ti consente di scegliere tra algoritmi di eliminazione dei picchi distinti impostando il valore su true o false, come spiegato di seguito:

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

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

Variabili di flusso

Quando viene eseguito un criterio SpikeArrest, vengono compilate le seguenti variabili di flusso:

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

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

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.

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>

Il codice di stato HTTP attuale per il superamento di un limite di frequenza impostato da una quota o da un criterio SpikeArrest è 429 (Troppe richieste).

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 alle quote e SpikeArrest