Limitare la frequenza delle chiamate in base alla chiave

  • Articolo

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium

Il criterio rate-limit-by-key impedisce picchi d'uso dell'API per ogni chiave impostando la frequenza delle chiamate su un numero specificato per un periodo di tempo specificato. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri. Per specificare le richieste da considerare nel limite, è possibile aggiungere una condizione opzionale di incremento. Quando questa frequenza di chiamata viene superata, il chiamante riceve un 429 Too Many Requests codice di stato della risposta.

Per comprendere la differenza tra limiti di velocità e quote, vedere Limiti di frequenza e quote.

Attenzione

A causa della natura distribuita dell'architettura di limitazione, la limitazione della velocità non è mai completamente accurata. La differenza tra le richieste configurate e il numero attuale di richieste consentite varia in base al volume e alla frequenza delle richieste, alla latenza del back-end e ad altri fattori.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione dei criteri. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di Gestione API.

Istruzione del criterio

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   increment-count="number"
                   counter-key="key value" 
                   retry-after-header-name="custom header name, replaces default 'Retry-After'" 
                   retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  
                   remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/>

Attributi

Attributo Descrizione Richiesto Valore predefinito
calls Il numero totale massimo di chiamate consentite durante l'intervallo di tempo specificato in renewal-period. Le espressioni di criteri sono consentite. Sì N/D
counter-key La chiave deve essere usata per i criteri relativi ai limiti di frequenza. Per ogni valore di chiave, viene usato un singolo contatore per tutti gli ambiti in cui è configurato il criterio. Le espressioni di criteri sono consentite. Sì N/D
increment-condition Espressione booleana che specifica se la richiesta deve essere conteggiata in base alla frequenza (true). Le espressioni di criteri sono consentite. No N/D
numero di incrementi Numero in base al quale il contatore viene aumentato per richiesta. Le espressioni di criteri sono consentite. No 1
renewal-period Lunghezza in secondi della finestra temporale scorrevole durante la quale il numero di richieste consentite non deve superare il valore specificato in calls. Valore massimo consentito: 300 secondi. Le espressioni di criteri sono consentite. Sì N/D
retry-after-header-name Nome di un'intestazione di risposta personalizzata il cui valore è l'intervallo di ripetizione consigliato in secondi dopo il superamento della frequenza di chiamata specificata. Le espressioni di criteri non sono consentite. No Retry-After
retry-after-variable-name Nome di una variabile di espressione di criteri che archivia l'intervallo di ripetizione dei tentativi consigliato in secondi dopo il superamento della frequenza di chiamata specificata. Le espressioni di criteri non sono consentite. No N/D
remaining-calls-header-name Nome di un'intestazione di risposta il cui valore dopo ogni esecuzione dei criteri è il numero di chiamate rimanenti consentite per l'intervallo di tempo specificato in renewal-period. Le espressioni di criteri non sono consentite. No N/D
remaining-calls-variable-name Nome di una variabile di espressione di criteri che dopo ogni esecuzione dei criteri archivia il numero di chiamate rimanenti consentite per l'intervallo di tempo specificato in renewal-period. Le espressioni di criteri non sono consentite. No N/D
total-calls-header-name Nome di un'intestazione di risposta il cui valore è il valore specificato in calls. Le espressioni di criteri non sono consentite. No N/D

Utilizzo

Note sull'utilizzo

  • I conteggi dei limiti di frequenza in un gateway self-hosted possono essere configurati per la sincronizzazione locale (tra le istanze del gateway tra i nodi del cluster), ad esempio tramite la distribuzione del grafico Helm per Kubernetes o usando i modelli di distribuzione portale di Azure. Tuttavia, i conteggi dei limiti di frequenza non vengono sincronizzati con altre risorse del gateway configurate nell'istanza di Gestione API, incluso il gateway gestito nel cloud. Ulteriori informazioni

Esempio

Nell'esempio seguente, il limite di frequenza di 10 chiamate per 60 secondi viene chiaveto dall'indirizzo IP del chiamante. Dopo ogni esecuzione dei criteri, le chiamate rimanenti consentite nel periodo di tempo vengono archiviate nella variabile remainingCallsPerIP.

<policies>
    <inbound>
        <base />
        <rate-limit-by-key  calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Per altre informazioni ed esempi su questo criterio, vedere Advanced request throttling with Azure API Management (Limitazione avanzata delle richieste con Gestione API di Azure).

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: