Share via

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

  • Articolo

Nota

Azure Spring Apps è il nuovo nome del servizio Azure Spring Cloud. Anche se il servizio ha un nuovo nome, il nome precedente verrà visualizzato in alcune posizioni per un po' mentre si lavora per aggiornare gli asset, ad esempio screenshot, video e diagrammi.

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 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, 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 API commerciali 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 le 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 della route. Per altre informazioni, vedere Usare il portale API per VMware Tanzu.

Prerequisiti

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 GatewayFilter factory usate per creare filtri per le route. Le sezioni seguenti descrivono queste factory.

AddRequestHeader

La AddRequestHeader factory 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 AddRequestHeader factory 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 AddRequestHeader factory 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 AddRequestHeader factory che usa una variabile:

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

AddRequestHeadersIfNotPresent

La AddRequestHeadersIfNotPresent factory 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).

L'esempio seguente configura una AddRequestHeadersIfNotPresent factory:

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

AddRequestParameter

La AddRequestParameter factory 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 AddRequestParameter factory che aggiunge un red=blue parametro alla stringa di query della richiesta downstream per tutte le richieste corrispondenti:

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

La AddRequestParameter factory 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 AddRequestParameter factory che usa una variabile:

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

AddResponseHeader

La AddResponseHeader factory 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 AddResponseHeader factory che aggiunge un'intestazione X-Response-Red:Blue alle intestazioni della risposta downstream per tutte le richieste corrispondenti:

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

La AddResponseHeader factory 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 AddResponseHeader factory che usa una variabile:

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

CircuitBreaker

La factory esegue il CircuitBreaker 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.

L'esempio seguente configura una CircuitBreaker factory:

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

DeDupeResponseHeader

La DeDupeResponseHeader factory 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_LASTe RETAIN_UNIQUE. Il valore predefinito è RETAIN_FIRST.

L'esempio seguente configura una DeDupeResponseHeader factory che rimuove i valori duplicati delle intestazioni di Access-Control-Allow-Credentials risposta 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 FallbackHeaders factory aggiunge qualsiasi eccezione di interruttore a un'intestazione. Questo filtro richiede l'uso del CircuitBreaker filtro in un'altra route.

Non esistono parametri per questa factory.

Nell'esempio seguente viene configurata una FallbackHeaders factory con il tipo di eccezione, il messaggio e (se disponibile) il tipo di eccezione della causa radice e il messaggio che il FallbackHeaders filtro 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 JSONToGRPCFilter factory 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 --descriptor_set_out flag , 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 streaming parametro non è supportato.

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

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

LocalResponseCache

La LocalResponseCache factory 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 s di durata per secondi, m per minuti o h per ore.

L'esempio seguente configura una LocalResponseCache factory:

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

MapRequestHeader

La MapRequestHeader factory 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 MapRequestHeader factory che aggiunge l'intestazione X-Request-Red:<values> alla richiesta downstream con valori aggiornati dall'intestazione della Blue richiesta HTTP in ingresso:

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

PrefixPath

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

Questa factory accetta il parametro di configurazione seguente:

  • prefix

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

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

PreserveHostHeader

La PreserveHostHeader factory 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.

L'esempio seguente configura una PreserveHostHeader factory:

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

RedirectTo

La RedirectTo factory 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 RedirectTo factory che invia uno stato 302 con un'intestazione Location:https://acme.org per eseguire un reindirizzamento:

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

RemoveJsonAttributesResponseBody

La RemoveJsonAttributesResponseBody factory 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.

L'esempio seguente configura una RemoveJsonAttributesResponseBody factory:

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

RemoveRequestHeader

La RemoveRequestHeader factory 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 RemoveRequestHeader factory che rimuove l'intestazione X-Request-Foo prima dell'invio a valle:

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

RemoveRequestParameter

La RemoveRequestParameter factory 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 RemoveRequestParameter factory che rimuove il red parametro prima dell'invio a valle:

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

RemoveResponseHeader

La RemoveResponseHeader factory 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 RemoveResponseHeader factory che rimuove l'intestazione X-Response-Foo dalla risposta prima che venga restituita al client del gateway:

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

RequestHeaderSize

La RequestHeaderSize factory 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.

L'elenco seguente configura una RequestHeaderSize factory che invia uno stato 431 se le dimensioni di un'intestazione di richiesta sono maggiori di 1000 byte:

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

RewriteLocationResponseHeader

La RewriteLocationResponseHeader factory modifica il valore dell'intestazione Location della risposta, 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_REQUESTe 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 host:port parte dell'intestazione della risposta Location quando specificato. Se non viene specificato, viene usato il valore dell'intestazione della Host richiesta.

  • protocolsRegex: espressione regolare Stringvalida con cui viene confrontato il nome del protocollo. Se non corrisponde, il filtro non funziona. Il valore predefinito è http|https|ftp|ftps.

  • locationHeaderName

L'elenco seguente configura una RewriteLocationResponseHeader factory:

[
    {
        "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.

RiscriverePath

La RewritePath factory 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 RewritePath factory:

[
    {
        "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 RewriteResponseHeader factory 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

L'esempio seguente configura una RewriteResponseHeader factory:

[
    {
        "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 SetPath factory 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

L'esempio seguente configura una SetPath factory:

[
    {
        "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 SetRequestHeader factory 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 SetRequestHeader factory:

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

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

La SetRequestHeader factory 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 SetRequestHeader factory che usa una variabile:

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

SetResponseHeader

La SetResponseHeader factory 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 SetResponseHeader factory:

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

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

La SetResponseHeader factory 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 SetResponseHeader factory che usa una variabile:

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

SetStatus

La SetStatus factory 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, 404ad esempio , o la rappresentazione di stringa dell'enumerazione, ad esempio NOT_FOUND.

L'elenco seguente configura una SetStatus factory:

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

StripPrefix

La StripPrefix factory 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 a valle. Il valore predefinito è 1.

L'esempio seguente configura una StripPrefix factory:

[
    {
        "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 Retry factory 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 Retry filtro, se abilitato:

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

L'esempio seguente configura una Retry factory:

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

RequestSize

La RequestSize factory 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:

  • maxSizeDataSize: tipo in cui i valori sono definiti come un numero seguito da un suffisso facoltativoDataUnit, KB ad esempio 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 RequestSize factory:

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

In questo esempio, quando la richiesta viene rifiutata a causa delle dimensioni, la RequestSize factory 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 TokenRelay factory inoltra un OAuth2 token di accesso alle risorse downstream. Questo filtro è configurato come boolean valore nella definizione di route anziché come filtro esplicito.

L'esempio seguente configura una TokenRelay factory:

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

Usare filtri commerciali

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

AllowedRequestCookieCount

La AllowedRequestCookieCount factory 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 AllowedRequestCookieCount factory:

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

AllowedRequestHeadersCount

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

Questa factory accetta il parametro di configurazione seguente:

  • amount: numero di intestazioni consentite.

L'esempio seguente configura una AllowedRequestHeadersCount factory:

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

AllowedRequestQueryParamsCount

La AllowedRequestQueryParamsCount factory determina se una richiesta corrispondente può continuare 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 AllowedRequestQueryParamsCount factory:

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

BasicAuth

La BasicAuth factory aggiunge un'intestazione BasicAuthAuthorization alle richieste.

Non esistono parametri per questa factory.

L'esempio seguente configura una BasicAuth factory:

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

ClaimHeader

La ClaimHeader factory 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 ClaimHeader factory:

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

ClientCertificateHeader

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

Questa factory accetta i parametri di configurazione seguenti:

  • domain patternX-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 ClientCertificateHeader factory:

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

Cors

La Cors factory 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 Cors factory:

[
    {
        "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 JsonToXml factory 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 JsonToXml factory:

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

RateLimit

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

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 ssuffissi , m o h per specificare la durata in secondi, minuti o ore.
  • partition source (facoltativo): percorso della chiave di partizione (claim, headero IPs).
  • partition key (facoltativo): valore usato per partizionare i contatori delle richieste.

L'esempio seguente configura una RateLimit factory:

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

Gli esempi seguenti mostrano altre RateLimit configurazioni:

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 RestrictRequestHeaders factory determina se una richiesta corrispondente può continuare in base alle intestazioni.

Se sono presenti intestazioni HTTP che non si trovano nella configurazione senza distinzione tra maiuscole headerList 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 RestrictRequestHeaders factory:

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

RewriteAllResponseHeaders

La RewriteAllResponseHeaders factory 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 RewriteAllResponseHeaders factory:

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

RewriteResponseBody

La RewriteResponseBody factory 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 formato 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 RewriteResponseBody factory:

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

RewriteJsonAttributesResponseBody

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

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

  • jsonpathJSONPath: espressione che deve corrispondere al corpo della risposta.
  • replacement: valore di sostituzione.

L'esempio seguente configura una RewriteJsonAttributesResponseBody factory:

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

Ruoli

La Roles factory 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 Roles factory:

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

Ambiti

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

Questa factory accetta il parametro di configurazione seguente:

  • scopes: elenco delimitato da virgole di ambiti autorizzati OAuth .

L'esempio seguente configura una Scopes factory:

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

StoreIpAddress

La StoreIPAddress factory 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 StoreIPAddress factory:

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

Accesso SSO

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

L'esempio seguente configura una SSO login factory:

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

StoreHeader

La StoreHeader factory 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 StoreHeader factory:

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

XmlToJson

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

Non esistono parametri per questa factory.

L'esempio seguente configura una XmlToJson factory:

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

Passaggi successivi