Comment utiliser les filtres de routage VMware Spring Cloud Gateway avec le plan Entreprise d’Azure Spring Apps

Article
08/28/2024

Remarque

Les plans Essentiel, Standard et Entreprise seront déconseillés à compter de la mi-mars 2025, avec une période de mise hors service de 3 ans. Nous vous recommandons de passer à Azure Container Apps. Pour plus d’informations, consultez l’annonce de mise hors service d’Azure Spring Apps.

Le plan de consommation standard et dédiée sera déconseillé à compter du 30 septembre 2024, avec un arrêt complet après six mois. Nous vous recommandons de passer à Azure Container Apps. Pour plus d’informations, consultez Migrer le plan de consommation standard et dédiée Azure Spring Apps vers Azure Container Apps.

Cet article s’applique à :❌ De base/Standard ✔️ Entreprise

Cet article vous montre comment utiliser les filtres de routage VMware Spring Cloud Gateway avec le plan Entreprise d’Azure Spring Apps pour router les requêtes vers vos applications.

VMware Spring Cloud Gateway est un composant VMware Tanzu commercial basé sur le projet open source Spring Cloud Gateway. Spring Cloud Gateway gère les problèmes transversaux que rencontrent les équipes de développement d’API, comme l’authentification unique (SSO), le contrôle d’accès, la limitation du débit, la résilience, la sécurité, etc. Vous pouvez accélérer la livraison des API à l’aide de modèles modernes natifs Cloud et de n’importe quel langage de programmation pour le développement d’API.

VMware Spring Cloud Gateway propose les fonctionnalités suivantes :

Configuration du routage dynamique, indépendamment des applications individuelles qui peuvent être appliquées et modifiées sans recompilation.
Filtres de routes d’API commerciales pour le transport des revendications JWT (JSON Web Token) autorisées vers des services d’application.
Autorisation de certificat client.
Approches de limitation du débit.
Configuration du disjoncteur.
Prise en charge de l’accès aux services d’application via les informations d’identification d’authentification HTTP de base.

Pour son intégration au portail d’API pour VMware Tanzu, VMware Spring Cloud Gateway génère automatiquement la documentation d’OpenAPI version 3 après des ajouts ou des modifications à la configuration du routage. Pour plus d’informations, consultez Utiliser le portail d’API pour VMware Tanzu.

Prérequis

Une instance de service du plan Entreprise d’Azure Spring Apps déjà approvisionnée, avec Spring Cloud Gateway activé. Pour plus d’informations, consultez Démarrage rapide : Générer et déployer des applications sur Azure Spring Apps à l’aide du plan Enterprise.
Azure CLI version 2.0.67 ou ultérieure. Utilisez la commande suivante pour installer l’extension Azure Spring Apps : az extension add --name spring.

Utiliser des filtres

Vous utilisez des filtres dans votre configuration Spring Cloud Gateway pour agir sur la requête entrante ou la réponse sortante d’une configuration de route.

Par exemple, vous pouvez utiliser un filtre pour ajouter un en-tête HTTP ou refuser l’accès en fonction d’un jeton d’autorisation.

Utiliser des filtres open source

Le logiciel Open Source Spring Cloud Gateway comprend de nombreuses fabriques GatewayFilter qui sont utilisées pour créer des filtres pour les routes. Les sections suivantes décrivent ces fabriques.

AddRequestHeader

La fabrique AddRequestHeader ajoute un en-tête aux en-têtes de la requête en aval pour toutes les requêtes correspondantes.

Cette fabrique accepte les paramètres de configuration suivants :

name
value

L’exemple suivant configure une fabrique AddRequestHeader qui ajoute l’en-tête X-Request-red:blue aux en-têtes de la requête en aval pour toutes les requêtes correspondantes :

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

La fabrique AddRequestHeader a accès aux variables d’URI utilisées pour faire correspondre un chemin ou un hôte. Vous pouvez utiliser des variables d’URI dans la valeur et les variables sont développées au moment de l’exécution.

L’exemple suivant configure une fabrique AddRequestHeader qui utilise une variable :

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

AddRequestHeadersIfNotPresent

La fabrique AddRequestHeadersIfNotPresent ajoute des en-têtes s’ils ne sont pas présents dans la requête d’origine.

Cette fabrique accepte le paramètre de configuration suivant :

headers : une liste séparée par des virgules de paires clé-valeur (nom d’en-tête, valeur d’en-tête).

L’exemple suivant configure une fabrique AddRequestHeadersIfNotPresent :

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

AddRequestParameter

La fabrique AddRequestParameter ajoute un paramètre à la chaîne de requête de la requête en aval pour toutes les requêtes correspondantes.

Cette fabrique accepte les paramètres de configuration suivants :

name
value

L’exemple suivant configure une fabrique AddRequestParameter qui ajoute un paramètre red=blue à la chaîne de requête de la requête en aval pour toutes les requêtes correspondantes :

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

La fabrique AddRequestParameter a accès aux variables d’URI utilisées pour faire correspondre un chemin ou un hôte. Vous pouvez utiliser des variables d’URI dans la valeur et les variables sont développées au moment de l’exécution.

L’exemple suivant configure une fabrique AddRequestParameter qui utilise une variable :

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

AddResponseHeader

La fabrique AddResponseHeader ajoute un en-tête aux en-têtes de la réponse en aval pour toutes les requêtes correspondantes.

Cette fabrique accepte les paramètres de configuration suivants :

name
value

L’exemple suivant configure une fabrique AddResponseHeader qui ajoute un en-tête X-Response-Red:Blue aux en-têtes de la réponse en aval pour toutes les requêtes correspondantes :

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

La fabrique AddResponseHeader a accès aux variables d’URI utilisées pour faire correspondre un chemin ou un hôte. Vous pouvez utiliser des variables d’URI dans la valeur et les variables sont développées au moment de l’exécution.

L’exemple suivant configure une fabrique AddResponseHeader qui utilise une variable :

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

CircuitBreaker

La fabrique CircuitBreaker encapsule les routes dans un disjoncteur.

Cette fabrique accepte les paramètres de configuration suivants :

name : le nom du disjoncteur.
fallbackUri : l’URI de réacheminement, qui peut être une route locale ou un gestionnaire externe.
status codes (facultatif) : la liste séparée par des deux points des codes d’état à mettre en correspondance, au format numérique ou texte.
failure rate (facultatif) : le seuil au-dessus duquel le disjoncteur s’ouvre. La valeur par défaut est 50 %.
duration (facultatif) : le délai d’attente avant de se fermer à nouveau. La valeur par défaut est 60 secondes.

L’exemple suivant configure une fabrique CircuitBreaker :

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

DeDupeResponseHeader

La fabrique DeDupeResponseHeader supprime les valeurs en double des en-têtes de réponse.

Cette fabrique accepte les paramètres de configuration suivants :

name : une liste séparée par des espaces des noms d’en-têtes.
strategy (facultatif) : les valeurs acceptées sont RETAIN_FIRST, RETAIN_LAST et RETAIN_UNIQUE. La valeur par défaut est RETAIN_FIRST.

L’exemple suivant configure une fabrique DeDupeResponseHeader qui supprime les valeurs en double des en-têtes de réponse Access-Control-Allow-Credentials et Access-Control-Allow-Origin lorsque les deux valeurs sont ajoutées par la logique CORS de passerelle et la logique en aval :

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

FallbackHeaders

La fabrique FallbackHeaders ajoute toute exception disjoncteur à un en-tête. Ce filtre nécessite l’utilisation du filtre CircuitBreaker dans une autre route.

Il n’existe aucun paramètre pour cette fabrique.

L’exemple suivant configure une fabrique FallbackHeaders avec le type d’exception, le message et (si disponible) le type d’exception et le message d’exception de la cause racine ajoutés par le filtre FallbackHeaders à la requête :

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

Vous pouvez remplacer les noms des en-têtes dans la configuration en définissant les valeurs des paramètres suivants (mentionnées avec leurs valeurs par défaut) :

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

JSONToGRPC

La fabrique JSONToGRPCFilter convertit une charge utile JSON en requête gRPC.

Cette fabrique accepte le paramètre de configuration suivant :

protoDescriptor : un fichier de descripteur proto.

Vous pouvez générer ce fichier en utilisant protoc et en spécifiant l’indicateur --descriptor_set_out, comme illustré dans l’exemple suivant :

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

Remarque

Le paramètre streaming n’est pas pris en charge.

L’exemple suivant configure une fabrique JSONToGRPCFilter à l’aide de la sortie à partir de protoc :

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

LocalResponseCache

La fabrique LocalResponseCache remplace la configuration du cache de réponse local pour des routes spécifiques lorsque le cache global est activé.

Cette fabrique accepte les paramètres de configuration suivants :

size : la taille maximale autorisée des entrées de cache pour cette route avant le début de l’éviction du cache (en Ko, Mo et Go).
timeToLive : la durée de vie autorisée d’une entrée de cache avant expiration. Utilisez le suffixe s de durée pour les secondes, m pour les minutes ou h pour les heures.

L’exemple suivant configure une fabrique LocalResponseCache :

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

MapRequestHeader

La fabrique MapRequestHeader ajoute un en-tête à la requête en aval avec des valeurs mises à jour à partir de l’en-tête de la requête HTTP entrante.

Cette fabrique accepte les paramètres de configuration suivants :

fromHeader
toHeader

Cette fabrique crée un en-tête nommé (toHeader) et la valeur est extraite d’un en-tête nommé existant (fromHeader) à partir de la requête HTTP entrante. Si l’en-tête d’entrée n’existe pas, le filtre n’a aucun effet. Si le nouvel en-tête nommé existe déjà, ses valeurs sont augmentées avec les nouvelles valeurs.

L’exemple suivant configure une fabrique MapRequestHeader qui ajoute l’en-tête X-Request-Red:<values> à la requête en aval avec des valeurs mises à jour à partir de l’en-tête Blue de la requête HTTP entrante :

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

PrefixPath

La fabrique PrefixPath ajoute un préfixe au chemin d’accès de toutes les requêtes.

Cette fabrique accepte le paramètre de configuration suivant :

prefix

L’exemple suivant configure une fabrique PrefixPath qui ajoute le préfixe /api au chemin d’accès de toutes les requêtes, afin qu’une requête /catalog soit envoyée à /api/catalog :

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

PreserveHostHeader

La fabrique PreserveHostHeader définit un attribut de requête que le filtre de routage inspecte pour déterminer s’il faut envoyer l’en-tête de l’hôte d’origine ou l’en-tête de l’hôte déterminé par le client HTTP.

Il n’existe aucun paramètre pour cette fabrique.

L’exemple suivant configure une fabrique PreserveHostHeader :

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

RedirectTo

La fabrique RedirectTo ajoute une redirection à l’URL d’origine.

Cette fabrique accepte les paramètres de configuration suivants :

status : une série 300 redirige le code HTTP, tel que 301.
url : la valeur de l’en-tête Location. Doit être un URI valide. Pour les redirections relatives, vous devez utiliser uri: no://op comme l’URI de votre définition de route.

L’exemple suivant configure une fabrique RedirectTo qui envoie un état 302 avec un en-tête Location:https://acme.org pour effectuer une redirection :

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

RemoveJsonAttributesResponseBody

La fabrique RemoveJsonAttributesResponseBody supprime les attributs JSON et leurs valeurs des corps de réponse JSON.

Cette fabrique accepte les paramètres de configuration suivants :

attribute names : une liste séparée par des virgules des noms d’attributs à supprimer d’une réponse JSON.
delete recursively (facultatif, booléen) : une configuration qui supprime les attributs uniquement au niveau racine (false) ou de manière récursive (true). La valeur par défaut est false.

L’exemple suivant configure une fabrique RemoveJsonAttributesResponseBody :

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

RemoveRequestHeader

La fabrique RemoveRequestHeader supprime un en-tête de la requête en aval.

Cette fabrique accepte le paramètre de configuration suivant :

name : le nom de l’en-tête à supprimer.

Le listing suivant configure une fabrique RemoveRequestHeader qui supprime l’en-tête X-Request-Foo avant son envoi en aval :

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

RemoveRequestParameter

La fabrique RemoveRequestParameter supprime un paramètre avant son envoi en aval.

Cette fabrique accepte le paramètre de configuration suivant :

name : le nom du paramètre de requête à supprimer.

L’exemple suivant configure une fabrique RemoveRequestParameter qui supprime le paramètre red avant son envoi en aval :

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

RemoveResponseHeader

La fabrique RemoveResponseHeader supprime un en-tête de la réponse avant son retour au client de passerelle.

Cette fabrique accepte le paramètre de configuration suivant :

name : le nom de l’en-tête à supprimer.

Le listing suivant configure une fabrique RemoveResponseHeader qui supprime l’en-tête X-Response-Foo de la réponse avant son retour au client de passerelle :

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

RequestHeaderSize

La fabrique RequestHeaderSize détermine la taille de l’en-tête de requête.

Cette fabrique accepte les paramètres de configuration suivants :

maxSize : la taille maximale des données autorisée par l’en-tête de requête, y compris la clé et la valeur.
errorHeaderName : le nom de l’en-tête de réponse contenant un message d’erreur. Par défaut, le nom de l’en-tête de réponse est errorMessage.

Le listing suivant configure une fabrique RequestHeaderSize qui envoie un état 431 si la taille d’un en-tête de requête est supérieure à 1 000 octets :

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

RewriteLocationResponseHeader

La fabrique RewriteLocationResponseHeader modifie la valeur de l’en-tête de réponse Location, généralement pour se débarrasser des détails spécifiques au back-end.

Cette fabrique accepte les paramètres de configuration suivants :

stripVersionMode : ce paramètre a les valeurs possibles suivantes : NEVER_STRIP, AS_IN_REQUEST et ALWAYS_STRIP. La valeur par défaut est AS_IN_REQUEST.
- NEVER_STRIP : la version n’est pas supprimée, même si le chemin de requête d’origine ne contient aucune version.
- AS_IN_REQUEST : la version est supprimée uniquement si le chemin de requête d’origine ne contient aucune version.
- ALWAYS_STRIP : la version est toujours supprimée, même si le chemin de requête d’origine contient la version.
hostValue : ce paramètre est utilisé pour remplacer la partie host:port de l’en-tête de réponse Location lorsqu’il est fourni. S’il n’est pas fourni, la valeur de l’en-tête de requête Host est utilisée.
protocolsRegex: une expression régulière String valide, par rapport à laquelle le nom du protocole est mis en correspondance. S’il n’est pas mis en correspondance, le filtre ne fonctionne pas. La valeur par défaut est http|https|ftp|ftps.
locationHeaderName

Le listing suivant configure une fabrique RewriteLocationResponseHeader :

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

Dans cet exemple, pour une valeur de demande de POST api.example.com/some/object/name, la valeur d’en-tête de réponse Location de object-service.prod.example.net/v2/some/object/id est réécrite en tant que api.example.com/some/object/id.

RewritePath

La fabrique RewritePath utilise des expressions régulières Java pour un moyen flexible de réécrire le chemin de la requête.

Cette fabrique accepte les paramètres de configuration suivants :

regexp
replacement

Le listing suivant configure une fabrique RewritePath :

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

Dans cet exemple, pour un chemin de requête de /red/blue, cette configuration définit le chemin d’accès vers /blue avant d’effectuer la requête en aval.

RewriteResponseHeader

La fabrique RewriteResponseHeader utilise des expressions régulières Java pour un moyen flexible de réécrire la valeur d’en-tête de réponse.

Cette fabrique accepte les paramètres de configuration suivants :

name
regexp
replacement

L’exemple suivant configure une fabrique RewriteResponseHeader :

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

Dans cet exemple, pour une valeur d’en-tête de /42?user=ford&password=omg!what&flag=true, la configuration est définie sur /42?user=ford&password=***&flag=true après avoir effectué la requête en aval.

SetPath

La fabrique SetPath offre un moyen simple de manipuler le chemin de requête en autorisant les segments basés sur un modèle du chemin d’accès. Ce filtre utilise les modèles d’URI de Spring Framework et autorise plusieurs segments correspondants.

Cette fabrique accepte le paramètre de configuration suivant :

template

L’exemple suivant configure une fabrique SetPath :

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

Dans cet exemple, pour un chemin de requête de /red/blue, cette configuration définit le chemin d’accès vers /blue avant d’effectuer la requête en aval.

SetRequestHeader

La fabrique SetRequestHeader remplace (au lieu d’ajouter) tous les en-têtes par le nom donné.

Cette fabrique accepte les paramètres de configuration suivants :

name
value

Le listing suivant configure une fabrique SetRequestHeader :

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

Dans cet exemple, le serveur en aval a répondu par X-Request-Red:1234, et il est remplacé par X-Request-Red:Blue.

La fabrique SetRequestHeader a accès aux variables d’URI utilisées pour faire correspondre un chemin ou un hôte. Vous pouvez utiliser des variables d’URI dans la valeur et les variables sont développées au moment de l’exécution.

L’exemple suivant configure une fabrique SetRequestHeader qui utilise une variable :

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

SetResponseHeader

La fabrique SetResponseHeader remplace (au lieu d’ajouter) tous les en-têtes par le nom donné.

Cette fabrique accepte les paramètres de configuration suivants :

name
value

Le listing suivant configure une fabrique SetResponseHeader :

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

Dans cet exemple, le serveur en aval a répondu par X-Response-Red:1234, et il est remplacé par X-Response-Red:Blue.

La fabrique SetResponseHeader a accès aux variables d’URI utilisées pour faire correspondre un chemin ou un hôte. Vous pouvez utiliser des variables d’URI dans la valeur et les variables sont développées au moment de l’exécution.

L’exemple suivant configure une fabrique SetResponseHeader qui utilise une variable :

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

SetStatus

La fabrique SetStatus configure l’état de réponse de la requête de serveur.

Cette fabrique accepte le paramètre de configuration suivant :

status : une valeur Spring HttpStatus valide, qui peut être une valeur entière telle que 404, ou la représentation sous forme de chaîne de l’énumération, telle que NOT_FOUND.

Le listing suivant configure une fabrique SetStatus :

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

StripPrefix

La fabrique StripPrefix supprime le préfixe de la requête avant de l’envoyer en aval.

Cette fabrique accepte le paramètre de configuration suivant :

parts : le nombre de parties dans le chemin d’accès à supprimer de la requête avant de l’envoyer en aval. La valeur par défaut est 1.

L’exemple suivant configure une fabrique StripPrefix :

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

Dans cet exemple, une requête est effectuée via la passerelle vers /name/blue/red. La requête faite pour nameservice apparaît en tant que nameservice/red.

Réessayer

La fabrique Retry détermine le nombre de nouvelles tentatives tentées.

Cette fabrique accepte les paramètres de configuration suivants :

retries : le nombre de nouvelles tentatives qui doivent être tentées.
statuses : les codes d’état HTTP qui doivent être retentés, représentés à l’aide de org.springframework.http.HttpStatus.
methods : les méthodes HTTP qui doivent être retentées, représentées à l’aide de org.springframework.http.HttpMethod.
series : la série de codes d’état à retenter, représentée à l’aide de org.springframework.http.HttpStatus.Series.
exceptions : la liste des exceptions levées qui doivent être retentées.
backoff : le backoff exponentiel configuré pour les nouvelles tentatives. Les nouvelles tentatives sont effectuées après un intervalle d’interruption de firstBackoff * (factor ^ n), où n est l’itération. Si maxBackoff est configuré, l’interruption maximale appliquée est limitée à maxBackoff. Si basedOnPreviousValue est true, le backoff est calculé à l’aide de prevBackoff * factor.

Les valeurs par défaut suivantes sont configurées pour le filtre Retry, lorsqu’elles sont activées :

retries :trois fois.
series : série 5XX.
methods : méthode Get.
exceptions : IOException et TimeoutException.
backoff : désactivé.

L’exemple suivant configure une fabrique Retry :

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

RequestSize

La fabrique RequestSize peut restreindre une requête d’atteindre le service en aval lorsque la taille de la requête est supérieure à la limite autorisée.

Cette fabrique accepte le paramètre de configuration suivant :

maxSize : un type DataSize où les valeurs sont définies comme un nombre suivi d’un suffixe DataUnit facultatif tel que KB ou MB. La valeur de suffixe par défaut est B pour les octets. Il s’agit de la limite de taille autorisée de la requête définie en octets.

L’exemple suivant configure une fabrique RequestSize :

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

Dans cet exemple, lorsque la requête est rejetée en raison de sa taille, la fabrique RequestSize définit l’état de la réponse sur 413 Payload Too Large avec un autre en-tête errorMessage.

L’exemple suivant montre un errorMessage :

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

TokenRelay

La fabrique TokenRelay transfère un jeton d’accès OAuth2 aux ressources en aval. Ce filtre est configuré comme valeur boolean dans la définition de route plutôt que comme un filtre explicite.

L’exemple suivant configure une fabrique TokenRelay :

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

Utilisez des filtres commerciaux

Spring Cloud Gateway pour Kubernetes fournit également de nombreuses fabriques GatewayFilter personnalisées. Les sections suivantes décrivent ces fabriques.

AllowedRequestCookieCount

La fabrique AllowedRequestCookieCount détermine si une demande correspondante est autorisée à continuer en fonction du nombre de cookies.

Cette fabrique accepte le paramètre de configuration suivant :

amount : le nombre de cookies autorisés.

L’exemple suivant configure une fabrique AllowedRequestCookieCount :

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

AllowedRequestHeadersCount

La fabrique AllowedRequestHeadersCount détermine si une demande correspondante est autorisée à continuer en fonction du nombre d’en-têtes.

Cette fabrique accepte le paramètre de configuration suivant :

amount : le nombre d’en-têtes autorisés.

L’exemple suivant configure une fabrique AllowedRequestHeadersCount :

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

AllowedRequestQueryParamsCount

La fabrique AllowedRequestQueryParamsCount détermine si une requête correspondante est autorisée à continuer en fonction du nombre de paramètres de la requête.

Cette fabrique accepte le paramètre de configuration suivant :

amount : le nombre de paramètres autorisés.

L’exemple suivant configure une fabrique AllowedRequestQueryParamsCount :

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

BasicAuth

La fabrique BasicAuth ajoute un en-tête BasicAuth Authorization aux requêtes.

Il n’existe aucun paramètre pour cette fabrique.

L’exemple suivant configure une fabrique BasicAuth :

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

ClaimHeader

La fabrique ClaimHeader copie les données d’une revendication JWT dans un en-tête HTTP.

Cette fabrique accepte les paramètres de configuration suivants :

Claim name : le nom sensible à la casse de la revendication à passer.
Header name : le nom de l’en-tête HTTP.

L’exemple suivant configure une fabrique ClaimHeader :

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

ClientCertificateHeader

La fabrique ClientCertificateHeader valide le certificat d’en-tête X-Forwarded-Client-Cert.

Cette fabrique accepte les paramètres de configuration suivants :

domain pattern : la valeur X-Forwarded-Client-Cert en fonction de la capacité de Kubernetes à reconnaître l’autorité de certification du certificat client.
certificate fingerprint (facultatif) : l’empreinte digitale du certificat TLS/SSL.

L’exemple suivant configure une fabrique ClientCertificateHeader :

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

Cors

La fabrique Cors active les validations CORS sur une route.

Cette fabrique accepte les paramètres de configuration suivants qui sont organisés en tant que paires clé-valeur pour les options CORS :

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

L’exemple suivant configure une fabrique 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 fabrique JsonToXml transforme le corps de la réponse JSON en corps de réponse XML.

Cette fabrique accepte le paramètre de configuration suivant :

wrapper : le nom de balise racine de la réponse XML si une autre balise racine est requise pour générer du code XML valide. La valeur par défaut est response.

L’exemple suivant configure une fabrique JsonToXml :

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

RateLimit

La fabrique RateLimit détermine si une requête correspondante est autorisée à continuer en fonction du volume de la requête.

Cette fabrique accepte les paramètres de configuration suivants :

request limit : le nombre maximal de requêtes acceptées pendant la fenêtre.
window duration : la durée de la fenêtre en millisecondes. Vous pouvez également utiliser les suffixes s, m ou h pour spécifier la durée en secondes, en minutes ou en heures.
partition source (facultatif) : l’emplacement de la clé de partition (claim, header ou IPs).
partition key (facultatif) : la valeur utilisée pour partitionner les compteurs de requête.

L’exemple suivant configure une fabrique RateLimit :

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

Les exemples suivants montrent d’autres configurations 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 fabrique RestrictRequestHeaders détermine si une demande correspondante est autorisée à continuer en fonction des d’en-têtes.

S’il existe des en-têtes HTTP qui ne sont pas dans la configuration headerList insensible à la casse, une réponse de 431 Forbidden error est retournée au client.

Cette fabrique accepte le paramètre de configuration suivant :

headerList : la liste insensible à la casse des noms d’en-têtes autorisés.

L’exemple suivant configure une fabrique RestrictRequestHeaders :

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

RewriteAllResponseHeaders

La fabrique RewriteAllResponseHeaders réécrit plusieurs en-têtes de réponse à la fois.

Cette fabrique accepte les paramètres de configuration suivants :

pattern to match : l’expression régulière à mettre en correspondance avec les valeurs d’en-tête.
replacement : la valeur de remplacement.

L’exemple suivant configure une fabrique RewriteAllResponseHeaders :

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

RewriteResponseBody

La fabrique RewriteResponseBody modifie le corps d’une réponse.

Cette fabrique accepte les paramètres de configuration suivants, organisés sous la forme d’une liste de paires clé-valeur séparées par des virgules, où chaque paire prend la forme pattern to match:replacement :

pattern to match : l’expression régulière à mettre en correspondance avec le texte dans le corps de la réponse.
replacement : la valeur de remplacement.

L’exemple suivant configure une fabrique RewriteResponseBody :

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

RewriteJsonAttributesResponseBody

La fabrique RewriteJsonAttributesResponseBody réécrit les attributs JSON à l’aide de la notation JSONPath.

jsonpath : l’expression JSONPath à mettre en correspondance avec le corps de la réponse.
replacement : la valeur de remplacement.

L’exemple suivant configure une fabrique RewriteJsonAttributesResponseBody :

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

Rôles

La fabrique Roles autorise les requêtes qui contiennent l’un des rôles configurés.

Cette fabrique accepte le paramètre de configuration suivant :

roles : une liste des rôles autorisés séparés par des virgules.

L’exemple suivant configure une fabrique Roles :

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

Étendues

La fabrique Scopes autorise les requêtes qui contiennent l’un des rôles configurés OAuth.

Cette fabrique accepte le paramètre de configuration suivant :

scopes : une liste des étendues autorisées OAuth séparées par des virgules.

L’exemple suivant configure une fabrique Scopes :

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

StoreIpAddress

La fabrique StoreIPAddress est utilisée uniquement pour le développement d’extensions et dans le contexte de l’application.

Cette fabrique accepte le paramètre de configuration suivant :

attribute name : le nom utilisé pour stocker l’adresse IP en tant qu’attribut d’échange.

L’exemple suivant configure une fabrique StoreIPAddress :

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

La fabrique SSO login redirige vers l’authentification s’il n’existe aucun jeton d’autorisation valide. Cette fabrique est configurée comme valeur boolean dans la définition de route plutôt que comme filtre explicite.

L’exemple suivant configure une fabrique SSO login :

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

StoreHeader

La fabrique StoreHeader stocke une valeur d’en-tête dans le contexte de l’application. Ce filtre est utilisé uniquement pour le développement d’extensions.

Cette fabrique accepte les paramètres de configuration suivants :

headers : une liste d’en-têtes à vérifier. Le premier trouvé est utilisé.
attribute name : le nom utilisé pour stocker la valeur d’en-tête en tant qu’attribut d’échange.

L’exemple suivant configure une fabrique StoreHeader :

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

XmlToJson

La fabrique XmlToJson transforme le corps de la réponse XML en corps de réponse JSON.

Il n’existe aucun paramètre pour cette fabrique.

L’exemple suivant configure une fabrique XmlToJson :

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

Partager via

Comment utiliser les filtres de routage VMware Spring Cloud Gateway avec le plan Entreprise d’Azure Spring Apps

Prérequis

Utiliser des filtres

Utiliser des filtres 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

Réessayer

RequestSize

TokenRelay

Utilisez des filtres commerciaux

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

BasicAuth

ClaimHeader

ClientCertificateHeader

Cors

JsonToXml

RateLimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

Rôles

Étendues

StoreIpAddress

Connexion d’authentification unique

StoreHeader

XmlToJson

Étapes suivantes

Commentaires

Ressources supplémentaires