Limita la frequenza delle chiamate per chiave

  • Articolo

SI APPLICA A: Developer | 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 viene superata la frequenza delle chiamate, il chiamante riceve il codice di stato della risposta 429 Too Many Requests.

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 delle richieste, la limitazione della frequenza 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 del criterio. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di API Management.

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 Numero totale massimo di chiamate consentite per il valore della chiave 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 ai fini della tariffa (true). Le espressioni di criteri sono consentite. No N/D
increment-count Numero in base al quale il contatore subisce un incremento per richiesta. Le espressioni di criteri sono consentite. No 1
renewal-period Durata 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 dei tentativi consigliato in secondi dopo il superamento della frequenza di chiamata per il valore della chiave. 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 chiamate specificato per il valore della chiave. 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 il valore della chiave nell'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 il valore della chiave nell'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

  • Gestione API usa un singolo contatore per ogni valore counter-key specificato nei criteri. Il contatore viene aggiornato in tutti gli ambiti in cui il criterio è configurato con tale valore della chiave. Se si vogliono configurare contatori separati in ambiti diversi, ad esempio, un'API o un prodotto specifico, specificare valori di chiave diversi nei diversi ambiti. Ad esempio, aggiungere una stringa che identifica l'ambito alla fine del valore di un'espressione.
  • Il numero di limiti di frequenza in un gateway self-hosted possono essere configurati per la sincronizzazione locale (tra le istanze del gateway nei nodi del cluster), ad esempio tramite la distribuzione del grafico Helm per Kubernetes o usando i modelli di distribuzione del portale di Azure. Tuttavia, i conteggi dei limiti di frequenza non vengono sincronizzati con altre risorse del gateway configurate nell'istanza di API Management, incluso il gateway gestito nel cloud. Ulteriori informazioni

Esempio

Nell'esempio seguente il limite alla frequenza di 10 chiamate per 60 secondi viene associato a una chiave dall'indirizzo IP del chiamante. Dopo ogni esecuzione dei criteri, le chiamate rimanenti consentite per tale indirizzo IP chiamante nel periodo di tempo vengono archiviati 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: