Come usare i filtri di route di VMware Spring Cloud Gateway con il piano Enterprise di Azure Spring Apps

Articolo
08/28/2024

Nota

I piani Basic, Standard ed Enterprise saranno deprecati a partire dalla metà di marzo 2025, con un periodo di ritiro di 3 anni. È consigliabile eseguire la transizione ad App Azure Container. Per altre informazioni, vedere l'annuncio di ritiro di Azure Spring Apps.

Il piano Standard a consumo e dedicato sarà deprecato a partire dal 30 settembre 2024, con un arresto completo dopo sei mesi. È consigliabile eseguire la transizione ad App Azure Container. Per altre informazioni, vedere Eseguire la migrazione del consumo di Azure Spring Apps Standard e del piano dedicato alle app Azure Container.

Questo articolo si applica a: ❎ Basic/Standard ✅ Enterprise

Questo articolo illustra come usare i filtri di route di VMware Spring Cloud Gateway con il piano Enterprise di Azure Spring Apps per instradare le richieste alle applicazioni.

VMware Spring Cloud Gateway è un componente VMware Tanzu commerciale basato sul progetto Spring Cloud Gateway open source. Spring Cloud Gateway gestisce le problematiche trasversali per i team di sviluppo di API, ad esempio Single Sign-On (SSO), il controllo di accesso, la limitazione della frequenza, la resilienza e la sicurezza, e altro ancora. È possibile accelerare il recapito delle API usando modelli nativi del cloud moderni e qualsiasi linguaggio di programmazione scelto per lo sviluppo di API.

VMware Spring Cloud Gateway include le funzionalità seguenti:

Configurazione del routing dinamico, indipendentemente da singole applicazioni che possono essere applicate e modificate senza ricompilazione.
Filtri di route dell'API commerciale per il trasporto di attestazioni JWT (Json Web Token) autorizzate ai servizi dell'applicazione.
Autorizzazione del certificato client.
Approcci di limitazione della frequenza.
Configurazione dell'interruttore.
Supporto per l'accesso ai servizi dell'applicazione tramite credenziali di autenticazione di base HTTP.

Per l'integrazione con il portale API per VMware Tanzu, VMware Spring Cloud Gateway genera automaticamente la documentazione OpenAPI versione 3 dopo eventuali aggiunte o modifiche alla configurazione di route. Per altre informazioni, vedere Usare il portale API per VMware Tanzu.

Prerequisiti

Un'istanza del servizio del piano Enterprise di Azure Spring Apps già con Spring Cloud Gateway abilitata. Per altre informazioni, vedere Avvio rapido: Creare e distribuire app in Azure Spring Apps usando il piano Enterprise.
Interfaccia della riga di comando di Azure versione 2.0.67 o successiva. Usare il comando seguente per installare l'estensione Azure Spring Apps: az extension add --name spring.

Uso dei filtri

Si usano filtri nella configurazione di Spring Cloud Gateway per agire sulla richiesta in ingresso o sulla risposta in uscita a una configurazione di route.

Ad esempio, è possibile usare un filtro per aggiungere un'intestazione HTTP o negare l'accesso in base a un token di autorizzazione.

Usare filtri open source

Spring Cloud Gateway OSS include diverse factory GatewayFilter usate per creare filtri per le route. Le sezioni seguenti descrivono queste factory.

AddRequestHeader

La factory AddRequestHeader aggiunge un'intestazione alle intestazioni della richiesta downstream per tutte le richieste corrispondenti.

Questa factory accetta i parametri di configurazione seguenti:

name
value

Nell'esempio seguente viene configurata una factory AddRequestHeader che aggiunge l'intestazione X-Request-red:blue alle intestazioni della richiesta downstream per tutte le richieste corrispondenti:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue"
        ]
    }
]

La factory AddRequestHeader ha accesso alle variabili URI usate per trovare una corrispondenza con un percorso o un host. È possibile usare le variabili URI nel valore e le variabili vengono espanse in fase di esecuzione.

Nell'esempio seguente viene configurata una factory AddRequestHeader che usa una variabile:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue-{segment}"
        ]
    }
]

AddRequestHeadersIfNotPresent

La factory AddRequestHeadersIfNotPresent aggiunge intestazioni se non sono presenti nella richiesta originale.

Questa factory accetta il parametro di configurazione seguente:

headers: elenco delimitato da virgole di coppie chiave-valore (nome intestazione, valore di intestazione).

Nell'esempio seguente viene configurata una factory AddRequestHeadersIfNotPresent:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
        ]
    }
]

AddRequestParameter

La factory AddRequestParameter aggiunge un parametro alla stringa di query della richiesta downstream per tutte le richieste corrispondenti.

Questa factory accetta i parametri di configurazione seguenti:

name
value

Nell'esempio seguente viene configurata una factory AddRequestParameter che aggiunge un parametro red=blue alla stringa di query della richiesta downstream per tutte le richieste corrispondenti:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestParameter=red, blue"
        ]
    }
]

La factory AddRequestParameter ha accesso alle variabili URI usate per trovare una corrispondenza con un percorso o un host. È possibile usare le variabili URI nel valore e le variabili vengono espanse in fase di esecuzione.

Nell'esempio seguente viene configurata una factory AddRequestParameter che usa una variabile:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestParameter=foo, bar-{segment}"
        ]
    }
]

AddResponseHeader

La factory AddResponseHeader aggiunge un'intestazione alle intestazioni della risposta downstream per tutte le richieste corrispondenti.

Questa factory accetta i parametri di configurazione seguenti:

name
value

Nell'esempio seguente viene configurata una factory AddResponseHeader che aggiunge l'intestazione X-Response-Red:Blue alle intestazioni di una risposta downstream per tutte le richieste corrispondenti:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddResponseHeader=X-Response-Red, Blue"
        ]
    }
]

La factory AddResponseHeader ha accesso alle variabili URI usate per trovare una corrispondenza con un percorso o un host. È possibile usare le variabili URI nel valore e le variabili vengono espanse in fase di esecuzione.

Nell'esempio seguente viene configurata una factory AddResponseHeader che usa una variabile:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddResponseHeader=foo, bar-{segment}"
        ]
    }
]

CircuitBreaker

La factory CircuitBreaker esegue il wrapping delle route in un interruttore.

Questa factory accetta i parametri di configurazione seguenti:

name: nome dell'interruttore.
fallbackUri: URI di reindirizzamento, che può essere una route locale o un gestore esterno.
status codes (facoltativo): elenco delimitato da due punti dei codici di stato da trovare, in formato numero o testo.
failure rate (facoltativo): soglia al di sopra della quale si apre l'interruttore. Il valore predefinito è 50%.
duration (facoltativo): tempo di attesa prima della chiusura di nuovo. Il valore predefinito è 60 secondi.

Nell'esempio seguente viene configurata una factory CircuitBreaker:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    }
]

DeDupeResponseHeader

La factory DeDupeResponseHeader rimuove i valori duplicati delle intestazioni di risposta.

Questa factory accetta i parametri di configurazione seguenti:

name: elenco delimitato da spazi di nomi di intestazione.
strategy (facoltativo): i valori accettati sono RETAIN_FIRST, RETAIN_LAST e RETAIN_UNIQUE. Il valore predefinito è RETAIN_FIRST.

Nell'esempio seguente viene configurata una factory DeDupeResponseHeader che rimuove i valori duplicati delle intestazioni di risposta Access-Control-Allow-Credentials e Access-Control-Allow-Origin quando entrambi i valori vengono aggiunti dalla logica CORS del gateway e dalla logica downstream:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "DeDupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin"
        ]
    }
]

FallbackHeaders

La factory FallbackHeaders aggiunge qualsiasi eccezione di interruttore a un'intestazione. Questo filtro richiede l'uso del filtro CircuitBreaker in un'altra route.

Non esistono parametri per questa factory.

Nell'esempio seguente viene configurata una factory FallbackHeaders con il tipo di eccezione, il messaggio e il tipo di eccezione della causa radice (se disponibile) e il messaggio che il filtro FallbackHeaders aggiunge alla richiesta:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    },
    {
        "predicates": [
            "Path=/inCaseOfFailureUseThis"
        ],
        "filters": [
            "FallbackHeaders"
        ]
    }
]

È possibile sovrascrivere i nomi delle intestazioni nella configurazione impostando i valori dei parametri seguenti (indicati con i relativi valori predefiniti):

executionExceptionTypeHeaderName ("Execution-Exception-Type")
executionExceptionMessageHeaderName ("Execution-Exception-Message")
rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")
rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

JSONToGRPC

La factory JSONToGRPCFilter converte un payload JSON in una richiesta gRPC.

Questa factory accetta il parametro di configurazione seguente:

protoDescriptor: un file di descrittore proto.

È possibile generare questo file usando protoc e specificando il flag --descriptor_set_out, come illustrato nell'esempio seguente:

protoc --proto_path=src/main/resources/proto/ \
    --descriptor_set_out=src/main/resources/proto/hello.pb \
    src/main/resources/proto/hello.proto

Nota

Il parametro streaming non è supportato.

Nell'esempio seguente viene configurata una factory JSONToGRPCFilter usando l'output di protoc:

[
    {
        "predicates": [
            "Path=/json/**"
        ],
        "filters": [
            "JsonToGrpc=file:proto/hello.pb,file:proto/hello.proto,HelloService,hello"
        ]
    }
]

LocalResponseCache

La factory LocalResponseCache esegue l'override della configurazione della cache delle risposte locale per route specifiche quando viene attivata la cache globale.

Questa factory accetta i parametri di configurazione seguenti:

size: dimensione massima consentita delle voci della cache per questa route prima dell'inizio della rimozione della cache (in KB, MB e GB).
timeToLive: durata consentita di una voce della cache prima della scadenza. Usare il suffisso di durata s per i secondi, m per i minuti o h per le ore.

Nell'esempio seguente viene configurata una factory LocalResponseCache:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "LocalResponseCache=3m,1MB"
        ]
    }
]

MapRequestHeader

La factory MapRequestHeader aggiunge un'intestazione alla richiesta downstream con valori aggiornati dall'intestazione della richiesta HTTP in ingresso.

Questa factory accetta i parametri di configurazione seguenti:

fromHeader
toHeader

Questa factory crea una nuova intestazione denominata (toHeader) e il valore viene estratto da un'intestazione denominata esistente (fromHeader) dalla richiesta HTTP in ingresso. Se l'intestazione di input non esiste, il filtro non ha alcun effetto. Se la nuova intestazione denominata esiste già, i relativi valori vengono aumentati con i nuovi valori.

Nell'esempio seguente viene configurata una factory MapRequestHeader che aggiunge l'intestazione X-Request-Red:<values> alla richiesta downstream con valori aggiornati dall'intestazione Blue della richiesta HTTP in ingresso:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "MapRequestHeader=Blue, X-Request-Red"
        ]
    }
]

PrefixPath

La factory PrefixPath aggiunge un prefisso al percorso di tutte le richieste.

Questa factory accetta il parametro di configurazione seguente:

prefix

Nell'esempio seguente viene configurata una factory PrefixPath che aggiunge il prefisso /api al percorso di tutte le richieste, in modo che una richiesta di /catalog venga inviata a /api/catalog:

[
    {
        "predicates": [
            "Path=/catalog/**"
        ],
        "filters": [
            "PrefixPath=/api"
        ]
    }
]

PreserveHostHeader

La factory PreserveHostHeader imposta un attributo di richiesta controllato dal filtro di routing per determinare se inviare l'intestazione host originale o l'intestazione host determinata dal client HTTP.

Non esistono parametri per questa factory.

Nell'esempio seguente viene configurata una factory PreserveHostHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "PreserveHostHeader"
        ]
    }
]

RedirectTo

La factory RedirectTo aggiunge un reindirizzamento all'URL originale.

Questa factory accetta i parametri di configurazione seguenti:

status: codice HTTP di reindirizzamento di serie 300, ad esempio 301.
url: valore dell'intestazione Location. Deve essere un URI valido. Per i reindirizzamenti relativi, è consigliabile usare uri: no://op come URI della definizione di route.

Nell'esempio seguente viene configurata una factory RedirectTo che invia un 302 di stato con un'intestazione Location:https://acme.org per eseguire un reindirizzamento:

[
    {
        "uri": "https://example.org",
        "filters": [
            "RedirectTo=302, https://acme.org"
        ]
    }
]

RemoveJsonAttributesResponseBody

La factory RemoveJsonAttributesResponseBody rimuove gli attributi JSON e i relativi valori dai corpi di risposta JSON.

Questa factory accetta i parametri di configurazione seguenti:

attribute names: elenco delimitato da virgole dei nomi degli attributi da rimuovere da una risposta JSON.
delete recursively (facoltativo, booleano): configurazione che rimuove gli attributi solo a livello radice (false) o in modo ricorsivo (true). Il valore predefinito è false.

Nell'esempio seguente viene configurata una factory RemoveJsonAttributesResponseBody:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveJsonAttributesResponseBody=origin,foo,true"
        ]
    }
]

RemoveRequestHeader

La factory RemoveRequestHeader rimuove un'intestazione dalla richiesta downstream.

Questa factory accetta il parametro di configurazione seguente:

name: nome dell'intestazione da rimuovere.

L'elenco seguente configura una factory RemoveRequestHeader che rimuove l'intestazione X-Request-Foo prima dell'invio a valle:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestHeader=X-Request-Foo"
        ]
    }
]

RemoveRequestParameter

La factory RemoveRequestParameter rimuove un parametro prima dell'invio a valle.

Questa factory accetta il parametro di configurazione seguente:

name: nome del parametro di query da rimuovere.

Nell'esempio seguente viene configurata una factory RemoveRequestParameter che rimuove il parametro red prima dell'invio a valle:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestParameter=red"
        ]
    }
]

RemoveResponseHeader

La factory RemoveResponseHeader rimuove un'intestazione dalla risposta prima che venga restituita al client del gateway.

Questa factory accetta il parametro di configurazione seguente:

name: nome dell'intestazione da rimuovere.

L'elenco seguente configura una factory RemoveResponseHeader che rimuove l'intestazione X-Response-Foo dalla risposta prima che venga restituita al client gateway:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveResponseHeader=X-Response-Foo"
        ]
    }
]

RequestHeaderSize

La factory RequestHeaderSize determina le dimensioni dell'intestazione della richiesta.

Questa factory accetta i parametri di configurazione seguenti:

maxSize: dimensione massima dei dati consentita dall'intestazione della richiesta, inclusa chiave e valore.
errorHeaderName: nome dell'intestazione della risposta contenente un messaggio di errore. Per impostazione predefinita, il nome dell'intestazione della risposta è errorMessage.

Nell'elenco seguente viene configurata una factory RequestHeaderSize che invia un 431 di stato se le dimensioni di un'intestazione di richiesta sono maggiori di 1000 byte:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RequestHeaderSize=1000B"
        ]
    }
]

RewriteLocationResponseHeader

La factory RewriteLocationResponseHeader modifica il valore dell'intestazione di risposta Location, in genere per eliminare i dettagli specifici del back-end.

Questa factory accetta i parametri di configurazione seguenti:

stripVersionMode: questo parametro ha i valori possibili seguenti: NEVER_STRIP, AS_IN_REQUEST e ALWAYS_STRIP. Il valore predefinito è AS_IN_REQUEST.
- NEVER_STRIP: la versione non viene rimossa, anche se il percorso della richiesta originale non contiene alcuna versione.
- AS_IN_REQUEST: la versione viene rimossa solo se il percorso della richiesta originale non contiene alcuna versione.
- ALWAYS_STRIP: la versione viene sempre rimossa, anche se il percorso della richiesta originale contiene la versione.
hostValue: questo parametro viene usato per sostituire la parte host:port dell’intestazione Location di risposta, se specificata. Se non viene specificato, viene usato il valore dell'intestazione della richiesta Host.
protocolsRegex: un'espressione regolare String valida, in base alla quale corrisponde il nome del protocollo. Se non corrisponde, il filtro non funziona. Il valore predefinito è http|https|ftp|ftps.
locationHeaderName

L'elenco seguente configura una factory RewriteLocationResponseHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,"
        ]
    }
]

In questo esempio, per un valore della richiesta di POSTapi.example.com/some/object/name, il valore dell'intestazione Location della risposta di object-service.prod.example.net/v2/some/object/id viene riscritto come api.example.com/some/object/id.

RewritePath

La factory RewritePath usa espressioni regolari Java per un modo flessibile per riscrivere il percorso della richiesta.

Questa factory accetta i parametri di configurazione seguenti:

regexp
replacement

L'elenco seguente configura una factory RewritePath:

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewritePath=/red/?(?<segment>.*), /$\\{segment}"
        ]
    }
]

In questo esempio, per un percorso di richiesta di /red/blue, questa configurazione imposta il percorso su /blue prima di effettuare la richiesta downstream.

RewriteResponseHeader

La factory RewriteResponseHeader usa espressioni regolari Java per un modo flessibile per riscrivere il valore dell'intestazione della risposta.

Questa factory accetta i parametri di configurazione seguenti:

name
regexp
replacement

Nell'esempio seguente viene configurata una factory RewriteResponseHeader:

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***"
        ]
    }
]

In questo esempio, per un valore di intestazione di /42?user=ford&password=omg!what&flag=true, la configurazione viene impostata su /42?user=ford&password=***&flag=true dopo aver effettuato la richiesta downstream.

SetPath

La factory SetPath offre un modo semplice per modificare il percorso della richiesta consentendo segmenti basati su modelli del percorso. Questo filtro usa i modelli URI di Spring Framework e consente più segmenti corrispondenti.

Questa factory accetta il parametro di configurazione seguente:

template

Nell'esempio seguente viene configurata una factory SetPath:

[
    {
        "predicates": [
            "Path=/red/{segment}"
        ],
        "filters": [
            "SetPath=/{segment}"
        ]
    }
]

In questo esempio, per un percorso di richiesta di /red/blue, questa configurazione imposta il percorso su /blue prima di effettuare la richiesta downstream.

SetRequestHeader

La factory SetRequestHeader sostituisce (anziché aggiungere) tutte le intestazioni con il nome specificato.

Questa factory accetta i parametri di configurazione seguenti:

name
value

L'elenco seguente configura una factory SetRequestHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetRequestHeader=X-Request-Red, Blue"
        ]
    }
]

In questo esempio il server downstream ha risposto con X-Request-Red:1234 e viene sostituito con X-Request-Red:Blue.

La factory SetRequestHeader ha accesso alle variabili URI usate per trovare una corrispondenza con un percorso o un host. È possibile usare le variabili URI nel valore e le variabili vengono espanse in fase di esecuzione.

Nell'esempio seguente viene configurata una factory SetRequestHeader che usa una variabile:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetRequestHeader=foo, bar-{segment}"
        ]
    }
]

SetResponseHeader

La factory SetResponseHeader sostituisce (anziché aggiungere) tutte le intestazioni con il nome specificato.

Questa factory accetta i parametri di configurazione seguenti:

name
value

L'elenco seguente configura una factory SetResponseHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetResponseHeader=X-Response-Red, Blue"
        ]
    }
]

In questo esempio il server downstream ha risposto con X-Response-Red:1234 e viene sostituito con X-Response-Red:Blue.

La factory SetResponseHeader ha accesso alle variabili URI usate per trovare una corrispondenza con un percorso o un host. È possibile usare le variabili URI nel valore e le variabili vengono espanse in fase di esecuzione.

Nell'esempio seguente viene configurata una factory SetResponseHeader che usa una variabile:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetResponseHeader=foo, bar-{segment}"
        ]
    }
]

SetStatus

La factory SetStatus configura lo stato della risposta della richiesta del server.

Questa factory accetta il parametro di configurazione seguente:

status: valore Spring HttpStatus valido, che può essere un valore intero, ad esempio 404 o la rappresentazione di stringa dell'enumerazione, ad esempio NOT_FOUND.

L'elenco seguente configura una factory SetStatus:

[
    {
        "predicates": [
            "Path=/experimental/**"
        ],
        "filters": [
            "SetStatus=UNAUTHORIZED"
        ]
    },
    {
        "predicates": [
            "Path=/unknown/**"
        ],
        "filters": [
            "SetStatus=401"
        ]
    }
]

StripPrefix

La factory StripPrefix rimuove il prefisso dalla richiesta prima di inviarlo a valle.

Questa factory accetta il parametro di configurazione seguente:

parts: numero di parti nel percorso da rimuovere dalla richiesta prima di inviarle downstream. Il valore predefinito è 1.

Nell'esempio seguente viene configurata una factory StripPrefix:

[
    {
        "predicates": [
            "Path=/name/**"
        ],
        "filters": [
            "StripPrefix=2"
        ]
    }
]

In questo esempio viene effettuata una richiesta tramite il gateway a /name/blue/red. La richiesta inviata a nameservice viene visualizzata come nameservice/red.

Riprova

La factory Retry determina il numero di tentativi tentati.

Questa factory accetta i parametri di configurazione seguenti:

retries: numero di tentativi che devono essere tentati.
statuses: codici di stato HTTP che devono essere ritentati, rappresentati tramite org.springframework.http.HttpStatus.
methods: metodi HTTP che devono essere ritentati, rappresentati tramite org.springframework.http.HttpMethod.
series: serie di codici di stato da ritentare, rappresentati tramite org.springframework.http.HttpStatus.Series.
exceptions: elenco di eccezioni generate che devono essere ritentate.
backoff: backoff esponenziale configurato per i tentativi. I tentativi vengono eseguiti dopo un intervallo di backoff di firstBackoff * (factor ^ n), dove n è l'iterazione. Se maxBackoff è configurato, il backoff massimo applicato è limitato a maxBackoff. Se basedOnPreviousValue è true, l'oggetto backoff viene calcolato utilizzando prevBackoff * factor.

Le impostazioni predefinite seguenti sono configurate per il filtro Retry, se abilitato:

retries: tre volte.
series: serie 5XX.
methods: metodo GET.
exceptions: IOException e TimeoutException.
backoff: disabilitato.

Nell'esempio seguente viene configurata una factory Retry:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false"
        ]
    }
]

RequestSize

La factory RequestSize può limitare il raggiungimento di una richiesta al servizio downstream quando la dimensione della richiesta è maggiore del limite consentito.

Questa factory accetta il parametro di configurazione seguente:

maxSize: tipo DataSize in cui i valori sono definiti come un numero seguito da un suffisso facoltativo DataUnit, ad esempio KB o MB. Il valore del suffisso predefinito è B per i byte. Si tratta del limite di dimensioni consentite della richiesta definita in byte.

L'esempio seguente configura una factory RequestSize:

[
    {
        "predicates": [
            "Path=/upload"
        ],
        "filters": [
            "RequestSize=5000000"
        ]
    }
]

In questo esempio, quando la richiesta viene rifiutata a causa delle dimensioni, la factory RequestSize imposta lo stato della risposta su 413 Payload Too Large con un'altra intestazione errorMessage.

L'esempio seguente mostra un oggetto errorMessage:

errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB

TokenRelay

La factory TokenRelay inoltra un token di accesso OAuth2 alle risorse downstream. Questo filtro viene configurato come valore boolean nella definizione di route anziché come filtro esplicito.

L'esempio seguente configura una factory TokenRelay:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "tokenRelay": true
    }
]

Usare filtri commerciali

Spring Cloud Gateway per Kubernetes offre anche molte factory GatewayFilter personalizzate. Le sezioni seguenti descrivono queste factory.

AllowedRequestCookieCount

La factory AllowedRequestCookieCount determina se una richiesta corrispondente può procedere in base al numero di cookie.

Questa factory accetta il parametro di configurazione seguente:

amount: numero di cookie consentiti.

L'esempio seguente configura una factory AllowedRequestCookieCount:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestCookieCount=2"
        ]
    }
]

AllowedRequestHeadersCount

La factory AllowedRequestHeadersCount determina se una richiesta corrispondente può procedere in base al numero di intestazioni.

Questa factory accetta il parametro di configurazione seguente:

amount: numero di intestazioni consentite.

L'esempio seguente configura una factory AllowedRequestHeadersCount:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestHeadersCount=4"
        ]
    }
]

AllowedRequestQueryParamsCount

La factory AllowedRequestQueryParamsCount determina se una richiesta corrispondente può procedere in base ai parametri di query numerici.

Questa factory accetta il parametro di configurazione seguente:

amount: numero di parametri consentiti.

L'esempio seguente configura una factory AllowedRequestQueryParamsCount:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestQueryParamsCount=3"
        ]
    }
]

BasicAuth

La factory BasicAuth aggiunge un'intestazione BasicAuth Authorization alle richieste.

Non esistono parametri per questa factory.

L'esempio seguente configura una factory BasicAuth:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "BasicAuth"
        ]
    }
]

ClaimHeader

La factory ClaimHeader copia i dati da un'attestazione JWT in un'intestazione HTTP.

Questa factory accetta i parametri di configurazione seguenti:

Claim name: nome con distinzione tra maiuscole e minuscole dell'attestazione da passare.
Header name: Nome dell'intestazione HTTP.

L'esempio seguente configura una factory ClaimHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClaimHeader=sub,X-Claim-Sub"
        ]
    }
]

ClientCertificateHeader

La factory ClientCertificateHeader convalida il certificato dell'intestazione X-Forwarded-Client-Cert.

Questa factory accetta i parametri di configurazione seguenti:

domain pattern X-Forwarded-Client-Cert : valore in base alla capacità di Kubernetes di riconoscere la CA del certificato client.
certificate fingerprint(facoltativo): impronta digitale del certificato TLS/SSL.

L'esempio seguente configura una factory ClientCertificateHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClientCertificateHeader=*.example.com,sha-1:aa:bb:00:99"
        ]
    }
]

Cors

La factory Cors attiva le convalide CORS in una route.

Questa factory accetta i parametri di configurazione seguenti organizzati come coppie chiave-valore per le opzioni CORS:

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

L'esempio seguente configura una factory Cors:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Cors=[allowedOrigins:https://origin-1,allowedMethods:GET;POST;DELETE,allowedHeaders:*,maxAge:400,allowCredentials:true,allowedOriginPatterns:https://*.test.com:8080]"
        ]
    }
]

JsonToXml

La factory JsonToXml trasforma il corpo della risposta JSON nel corpo della risposta XML.

Questa factory accetta il parametro di configurazione seguente:

wrapper: nome del tag radice per la risposta XML se è necessario un altro tag radice per generare codice XML valido. Il valore predefinito è response.

L'esempio seguente configura una factory JsonToXml:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "JsonToXml=custom-response"
        ]
    }
]

Ratelimit

La factory RateLimit determina se una richiesta corrispondente può continuare in base al volume della richiesta.

Questa factory accetta i parametri di configurazione seguenti:

request limit: numero massimo di richieste accettate durante la finestra.
window duration: durata della finestra in millisecondi. In alternativa, è possibile usare i suffissi s, m o h per specificare la durata in secondi, minuti o ore.
partition source (facoltativo): percorso della chiave di partizione (claim, header o IPs).
partition key (facoltativo): valore usato per partizionare i contatori delle richieste.

L'esempio seguente configura una factory RateLimit:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RateLimit=1,10s"
        ]
    }
]

Gli esempi seguenti illustrano altre configurazioni RateLimit:

RateLimit=1,10s
RateLimit=1,10s,{claim:client_id}
RateLimit=1,10s,{header:client_id}
RateLimit=2,10s,{IPs:2;127.0.0.1;192.168.0.1}

RestrictRequestHeaders

La factory RestrictRequestHeaders determina se una richiesta corrispondente può procedere in base alle intestazioni.

Se sono presenti intestazioni HTTP che non si trovano nella configurazione di headerList senza distinzione tra maiuscole e minuscole, viene restituita una risposta di 431 Forbidden error al client.

Questa factory accetta il parametro di configurazione seguente:

headerList: elenco senza distinzione tra maiuscole e minuscole dei nomi delle intestazioni consentite.

L'esempio seguente configura una factory RestrictRequestHeaders:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RestrictRequestHeaders=Content-Type,x-request-temp"
        ]
    }
]

RewriteAllResponseHeaders

La factory RewriteAllResponseHeaders riscrive più intestazioni di risposta contemporaneamente.

Questa factory accetta i parametri di configurazione seguenti:

pattern to match: espressione regolare che deve corrispondere ai valori dell'intestazione.
replacement: valore di sostituzione.

L'esempio seguente configura una factory RewriteAllResponseHeaders:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteAllResponseHeaders=\\d,0"
        ]
    }
]

RewriteResponseBody

La factory RewriteResponseBody modifica il corpo di una risposta.

Questa factory accetta i parametri di configurazione seguenti organizzati come elenco delimitato da virgole di coppie chiave-valore, in cui ogni coppia accetta il modulo pattern to match:replacement:

pattern to match: espressione regolare che deve corrispondere al testo nel corpo della risposta.
replacement: valore di sostituzione.

L'esempio seguente configura una factory RewriteResponseBody:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteResponseBody=foo:bar,/path-one/:/path-two/"
        ]
    }
]

RewriteJsonAttributesResponseBody

La factory RewriteJsonAttributesResponseBody riscrive gli attributi JSON usando la notazione JSONPath.

Questa factory accetta i parametri di configurazione seguenti organizzati come elenco delimitato da virgole di coppie chiave-valore, in cui ogni coppia accetta il modulo jsonpath:replacement:

jsonpath JSONPath : espressione che deve corrispondere al corpo della risposta.
replacement: valore di sostituzione.

L'esempio seguente configura una factory RewriteJsonAttributesResponseBody:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteJsonAttributesResponseBody=slides[1].title:Welcome,date:11-11-2022"
        ]
    }
]

Ruoli

La factory Roles autorizza le richieste che contengono uno dei ruoli configurati.

Questa factory accetta il parametro di configurazione seguente:

roles: elenco delimitato da virgole di ruoli autorizzati.

L'esempio seguente configura una factory Roles:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Roles=role_01,role_02"
        ]
    }
]

Ambiti

La factory Scopes autorizza le richieste che contengono uno degli ambiti OAuth configurati.

Questa factory accetta il parametro di configurazione seguente:

scopes: elenco delimitato da virgole di ambiti OAuth autorizzati.

L'esempio seguente configura una factory Scopes:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Scopes=api.read,api.write,user"
        ]
    }
]

StoreIpAddress

La factory StoreIPAddress viene usata solo per lo sviluppo di estensioni e nel contesto dell'applicazione.

Questa factory accetta il parametro di configurazione seguente:

attribute name: nome usato per archiviare l'indirizzo IP come attributo di scambio.

L'esempio seguente configura una factory StoreIPAddress:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreIpAddress=ip"
        ]
    }
]

La factory SSO login reindirizza per l'autenticazione se non è presente alcun token di autorizzazione valido. Questa factory viene configurata come valore boolean nella definizione di route anziché come filtro esplicito.

L'esempio seguente configura una factory SSO login:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "ssoEnabled": true
    }
]

StoreHeader

La factory StoreHeader archivia un valore di intestazione nel contesto dell'applicazione. Questo filtro viene usato solo per lo sviluppo di estensioni.

Questa factory accetta i parametri di configurazione seguenti:

headers: elenco di intestazioni da controllare. Viene usato il primo trovato.
attribute name: nome usato per archiviare il valore dell'intestazione come attributo di scambio.

L'esempio seguente configura una factory StoreHeader:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreHeader=x-tracing-header,custom-id,x-custom-id,tracingParam"
        ]
    }
]

XmlToJson

La factory XmlToJson trasforma il corpo della risposta XML nel corpo della risposta JSON.

Non esistono parametri per questa factory.

L'esempio seguente configura una factory XmlToJson:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "XmlToJson"
        ]
    }
]

Condividi tramite

Come usare i filtri di route di VMware Spring Cloud Gateway con il piano Enterprise di Azure Spring Apps

Prerequisiti

Uso dei filtri

Usare filtri open source

AddRequestHeader

AddRequestHeadersIfNotPresent

AddRequestParameter

AddResponseHeader

CircuitBreaker

DeDupeResponseHeader

FallbackHeaders

JSONToGRPC

LocalResponseCache

MapRequestHeader

PrefixPath

PreserveHostHeader

RedirectTo

RemoveJsonAttributesResponseBody

RemoveRequestHeader

RemoveRequestParameter

RemoveResponseHeader

RequestHeaderSize

RewriteLocationResponseHeader

RewritePath

RewriteResponseHeader

SetPath

SetRequestHeader

SetResponseHeader

SetStatus

StripPrefix

Riprova

RequestSize

TokenRelay

Usare filtri commerciali

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

BasicAuth

ClaimHeader

ClientCertificateHeader

Cors

JsonToXml

Ratelimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

Ruoli

Ambiti

StoreIpAddress

Accesso SSO

StoreHeader

XmlToJson

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive