Uso de filtros de ruta de VMware Spring Cloud Gateway con el plan Enterprise de Azure Spring Apps
Nota:
Azure Spring Apps es el nuevo nombre del servicio Azure Spring Cloud. Aunque el servicio tiene un nuevo nombre, verá el nombre antiguo en algunos lugares durante un tiempo mientras trabajamos para actualizar recursos, como capturas de pantalla, vídeos y diagramas.
Este artículo se aplica a:❌ Básico o Estándar ✔️ Enterprise
En este artículo se explica cómo usar filtros de ruta de VMware Spring Cloud Gateway con el plan Enterprise de Azure Spring Apps para enrutar las solicitudes a las aplicaciones.
Spring Cloud Gateway para VMware es un componente comercial de VMware Tanzu basado en el proyecto de código abierto Spring Cloud Gateway. Spring Cloud Gateway se encarga de las preocupaciones transversales de los equipos de desarrollo de API, como el inicio de sesión único (SSO), el control de acceso, la limitación de la velocidad, la resistencia, la seguridad, etc. Los patrones nativos de la nube modernos y cualquier lenguaje de programación que elija para el desarrollo de API pueden acelerar la entrega de API.
Spring Cloud Gateway para VMware incluye las siguientes características:
- Configuración dinámica del enrutamiento independiente de las aplicaciones individuales, que puede aplicarse y modificarse sin necesidad de volver a compilar.
- Filtros comerciales de rutas de API para transportar notificaciones de JSON Web Token (JWT) autorizadas a servicios de aplicación.
- Autorización de certificados de cliente.
- Enfoques que limitan la velocidad.
- Configuración de disyuntores.
- Compatibilidad con el acceso a los servicios de aplicación a través de credenciales de autenticación HTTP básica.
Para realizar la integración con el portal de API para VMware Tanzu, VMware Spring Cloud Gateway genera automáticamente la documentación de la versión 3 de OpenAPI después de cambios o adiciones en la configuración de la ruta. Para obtener más información, consulte Uso del portal de API para VMware Tanzu.
Requisitos previos
- Una instancia de servicio del plan Enterprise de Azure Spring Apps ya aprovisionada en la puerta de enlace Spring Cloud habilitado. Para más información, consulte Inicio rápido: Compilación e implementación de aplicaciones en Azure Spring Apps con el plan Enterprise.
- CLI de Azure, versión 2.0.67 o posterior. Use el siguiente comando para instalar la extensión de Azure Spring Apps:
az extension add --name spring
.
Utilizar filtros
Use filtros en la configuración de Spring Cloud Gateway para actuar sobre la solicitud entrante o la respuesta saliente a una configuración de ruta.
Por ejemplo, puede usar un filtro para agregar un encabezado HTTP o denegar el acceso en función de un token de autorización.
Uso de filtros de código abierto
El software de código abierto Spring Cloud Gateway incluye varias fábricas GatewayFilter
usadas para crear filtros para rutas. En las siguientes secciones se describen estas fábricas.
AddRequestHeader
La fábrica AddRequestHeader
agrega un encabezado a los encabezados de la solicitud de bajada para todas las solicitudes coincidentes.
Esta fábrica acepta los siguientes parámetros de configuración:
name
value
En el ejemplo siguiente se configura una fábrica AddRequestHeader
que agrega el encabezado X-Request-red:blue
a los encabezados de la solicitud de bajada para todas las solicitudes coincidentes:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AddRequestHeader=X-Request-red, blue"
]
}
]
La fábrica AddRequestHeader
tiene acceso a las variables de URI que se usan para buscar coincidencias con una ruta de acceso o host. Puede usar variables de URI en el valor y las variables se expanden en runtime.
En el ejemplo siguiente se configura una fábrica AddRequestHeader
que usa una variable:
[
{
"predicates": [
"Path=/api/{segment}"
],
"filters": [
"AddRequestHeader=X-Request-red, blue-{segment}"
]
}
]
AddRequestHeadersIfNotPresent
La fábrica AddRequestHeadersIfNotPresent
agrega encabezados si no están presentes en la solicitud original.
Esta fábrica acepta el siguiente parámetro de configuración:
headers
: una lista separada por comas de pares clave-valor (nombre de encabezado, valor de encabezado).
En el ejemplo siguiente se configura una fábrica AddRequestHeadersIfNotPresent
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
]
}
]
AddRequestParameter
La fábrica AddRequestParameter
agrega un parámetro a la cadena de consulta de la solicitud de bajada para todas las solicitudes coincidentes.
Esta fábrica acepta los siguientes parámetros de configuración:
name
value
En el ejemplo siguiente se configura una fábrica AddRequestParameter
que agrega un parámetro red=blue
a la cadena de consulta de la solicitud de bajada para todas las solicitudes coincidentes:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AddRequestParameter=red, blue"
]
}
]
La fábrica AddRequestParameter
tiene acceso a las variables de URI que se usan para buscar coincidencias con una ruta de acceso o host. Puede usar variables de URI en el valor y las variables se expanden en runtime.
En el ejemplo siguiente se configura una fábrica AddRequestParameter
que usa una variable:
[
{
"predicates": [
"Path=/api/{segment}"
],
"filters": [
"AddRequestParameter=foo, bar-{segment}"
]
}
]
AddResponseHeader
La fábrica AddResponseHeader
agrega un encabezado a los encabezados de la respuesta de bajada para todas las solicitudes coincidentes.
Esta fábrica acepta los siguientes parámetros de configuración:
name
value
En el ejemplo siguiente se configura una fábrica AddResponseHeader
que agrega un encabezado X-Response-Red:Blue
a los encabezados de la respuesta de bajada para todas las solicitudes coincidentes:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AddResponseHeader=X-Response-Red, Blue"
]
}
]
La fábrica AddResponseHeader
tiene acceso a las variables de URI que se usan para buscar coincidencias con una ruta de acceso o host. Puede usar variables de URI en el valor y las variables se expanden en runtime.
En el ejemplo siguiente se configura una fábrica AddResponseHeader
que usa una variable:
[
{
"predicates": [
"Path=/api/{segment}"
],
"filters": [
"AddResponseHeader=foo, bar-{segment}"
]
}
]
CircuitBreaker
La fábrica CircuitBreaker
encapsula las rutas en un disyuntor.
Esta fábrica acepta los siguientes parámetros de configuración:
name
: nombre del disyuntor.fallbackUri
: el URI de redireccionamiento, que puede ser una ruta local o un controlador externo.status codes
(opcional): lista separada por dos puntos de códigos de estado que deben coincidir, en formato numérico o de texto.failure rate
(opcional): umbral por encima del cual se abre el disyuntor. El valor predeterminado es 50 %.duration
(opcional): tiempo de espera antes de volver a cerrarse. El valor predeterminado es de 60 segundos.
En el ejemplo siguiente se configura una fábrica CircuitBreaker
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
]
}
]
DeDupeResponseHeader
La fábrica DeDupeResponseHeader
quita los valores duplicados de los encabezados de respuesta.
Esta fábrica acepta los siguientes parámetros de configuración:
name
: una lista separada por espacios de nombres de encabezado.strategy
(opcional): los valores aceptados sonRETAIN_FIRST
,RETAIN_LAST
yRETAIN_UNIQUE
. El valor predeterminado esRETAIN_FIRST
.
En el ejemplo siguiente se configura una fábrica DeDupeResponseHeader
que quita los valores duplicados de los encabezados de respuesta Access-Control-Allow-Credentials
y Access-Control-Allow-Origin
cuando la lógica CORS de la puerta de enlace agrega ambos valores y la lógica de bajada:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"DeDupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin"
]
}
]
FallbackHeaders
La fábrica FallbackHeaders
agrega cualquier excepción de disyuntor a un encabezado. Este filtro requiere el uso del filtro CircuitBreaker
en otra ruta.
No hay parámetros para esta fábrica.
En el ejemplo siguiente se configura una fábrica FallbackHeaders
con el tipo de excepción, el mensaje y el tipo de excepción de causa raíz (si está disponible) y el mensaje que el filtro FallbackHeaders
agrega a la solicitud:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
]
},
{
"predicates": [
"Path=/inCaseOfFailureUseThis"
],
"filters": [
"FallbackHeaders"
]
}
]
Puede sobrescribir los nombres de los encabezados de la configuración estableciendo los valores de los parámetros siguientes (mencionados con sus valores predeterminados):
executionExceptionTypeHeaderName
("Execution-Exception-Type")executionExceptionMessageHeaderName
("Execution-Exception-Message")rootCauseExceptionTypeHeaderName
("Root-Cause-Exception-Type")rootCauseExceptionMessageHeaderName
("Root-Cause-Exception-Message")
JSONToGRPC
La fábrica JSONToGRPCFilter
convierte una carga JSON en una solicitud gRPC.
Esta fábrica acepta el siguiente parámetro de configuración:
protoDescriptor
: un archivo proto descriptor.
Puede generar este archivo mediante protoc
y especificar la marca --descriptor_set_out
, como se muestra en el ejemplo siguiente:
protoc --proto_path=src/main/resources/proto/ \
--descriptor_set_out=src/main/resources/proto/hello.pb \
src/main/resources/proto/hello.proto
Nota:
No se admite el parámetro streaming
.
En el ejemplo siguiente se configura una fábrica JSONToGRPCFilter
mediante la salida de protoc
:
[
{
"predicates": [
"Path=/json/**"
],
"filters": [
"JsonToGrpc=file:proto/hello.pb,file:proto/hello.proto,HelloService,hello"
]
}
]
LocalResponseCache
La fábrica LocalResponseCache
invalida la configuración de caché de respuesta local para rutas específicas cuando se activa la caché global.
Esta fábrica acepta los siguientes parámetros de configuración:
size
: tamaño máximo permitido de las entradas de caché de esta ruta antes de que comience la expulsión de caché (en KB, MB y GB).timeToLive
: la duración permitida de una entrada de caché antes de la expiración. Use el sufijo de duracións
para segundos,m
para minutos oh
para horas.
En el ejemplo siguiente se configura una fábrica LocalResponseCache
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"LocalResponseCache=3m,1MB"
]
}
]
MapRequestHeader
La fábrica MapRequestHeader
agrega un encabezado a la solicitud de bajada con valores actualizados del encabezado de la solicitud HTTP entrante.
Esta fábrica acepta los siguientes parámetros de configuración:
fromHeader
toHeader
Esta fábrica crea un nuevo encabezado con nombre (toHeader
) y el valor se extrae de un encabezado con nombre existente (fromHeader
) de la solicitud HTTP entrante. Si el encabezado de entrada no existe, el filtro no tiene ningún efecto. Si el nuevo encabezado con nombre ya existe, sus valores se aumentan con los nuevos valores.
En el ejemplo siguiente se configura una fábrica MapRequestHeader
que agrega el encabezado X-Request-Red:<values>
a la solicitud de bajada con valores actualizados del encabezado Blue
de la solicitud HTTP entrante:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"MapRequestHeader=Blue, X-Request-Red"
]
}
]
PrefixPath
La fábrica PrefixPath
agrega un prefijo a la ruta de acceso de todas las solicitudes.
Esta fábrica acepta el siguiente parámetro de configuración:
prefix
En el ejemplo siguiente se configura una fábrica PrefixPath
que agrega el prefijo /api
a la ruta de acceso de todas las solicitudes, de modo que se envíe una solicitud /catalog
a /api/catalog
:
[
{
"predicates": [
"Path=/catalog/**"
],
"filters": [
"PrefixPath=/api"
]
}
]
PreserveHostHeader
La fábrica PreserveHostHeader
establece un atributo de solicitud que el filtro de enrutamiento inspecciona para determinar si se debe enviar el encabezado de host original o el encabezado de host determinado por el cliente HTTP.
No hay parámetros para esta fábrica.
En el ejemplo siguiente se configura una fábrica PreserveHostHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"PreserveHostHeader"
]
}
]
RedirectTo
La fábrica RedirectTo
agrega una redirección a la dirección URL original.
Esta fábrica acepta los siguientes parámetros de configuración:
status
: un código HTTP de redirección de la serie 300, como301
.url
: valor del encabezadoLocation
. Debe ser un URI válido. Para las redirecciones relativas, debe usaruri: no://op
como el URI de la definición de ruta.
En el ejemplo siguiente se configura una fábrica RedirectTo
que envía un 302
de estado con un encabezado Location:https://acme.org
para realizar una redirección:
[
{
"uri": "https://example.org",
"filters": [
"RedirectTo=302, https://acme.org"
]
}
]
RemoveJsonAttributesResponseBody
La fábrica RemoveJsonAttributesResponseBody
quita los atributos JSON y sus valores de los cuerpos de respuesta JSON.
Esta fábrica acepta los siguientes parámetros de configuración:
attribute names
: una lista separada por comas de los nombres de atributos que se van a quitar de una respuesta JSON.delete recursively
(opcional, booleano): configuración que quita los atributos solo en el nivel raíz (false
) o de forma recursiva (true
). El valor predeterminado esfalse
.
En el ejemplo siguiente se configura una fábrica RemoveJsonAttributesResponseBody
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RemoveJsonAttributesResponseBody=origin,foo,true"
]
}
]
RemoveRequestHeader
La fábrica RemoveRequestHeader
quita un encabezado de la solicitud de bajada.
Esta fábrica acepta el siguiente parámetro de configuración:
name
: nombre del encabezado que se va a quitar.
En la lista siguiente se configura una fábrica RemoveRequestHeader
que quita el encabezado X-Request-Foo
antes de enviarlo de bajada:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RemoveRequestHeader=X-Request-Foo"
]
}
]
RemoveRequestParameter
La fábrica RemoveRequestParameter
quita un parámetro antes de enviarlo de bajada.
Esta fábrica acepta el siguiente parámetro de configuración:
name
: nombre del parámetro de consulta que se va a quitar.
En el ejemplo siguiente se configura una fábrica RemoveRequestParameter
que quita el parámetro red
antes de enviarlo de bajada:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RemoveRequestParameter=red"
]
}
]
RemoveResponseHeader
La fábrica RemoveResponseHeader
quita un encabezado de la respuesta antes de que se devuelva al cliente de puerta de enlace.
Esta fábrica acepta el siguiente parámetro de configuración:
name
: nombre del encabezado que se va a quitar.
La lista siguiente configura una fábrica RemoveResponseHeader
que quita el encabezado X-Response-Foo
de la respuesta antes de que se devuelva al cliente de puerta de enlace:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RemoveResponseHeader=X-Response-Foo"
]
}
]
RequestHeaderSize
La fábrica RequestHeaderSize
determina el tamaño del encabezado de solicitud.
Esta fábrica acepta los siguientes parámetros de configuración:
maxSize
: tamaño máximo de datos permitido por el encabezado de solicitud, incluida la clave y el valor.errorHeaderName
: el nombre del encabezado de respuesta que contiene un mensaje de error. De forma predeterminada, el nombre del encabezado de respuesta eserrorMessage
.
La lista siguiente configura una fábrica RequestHeaderSize
que envía un estado 431
si el tamaño de cualquier encabezado de solicitud es mayor que 1000 bytes:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RequestHeaderSize=1000B"
]
}
]
RewriteLocationResponseHeader
La fábrica RewriteLocationResponseHeader
modifica el valor del encabezado de respuesta Location
, normalmente para deshacerse de detalles específicos del back-end.
Esta fábrica acepta los siguientes parámetros de configuración:
stripVersionMode
: este parámetro tiene los siguientes valores posibles:NEVER_STRIP
,AS_IN_REQUEST
yALWAYS_STRIP
. El valor predeterminado esAS_IN_REQUEST
.NEVER_STRIP
: la versión no se quita, incluso si la ruta de acceso de solicitud original no contiene ninguna versión.AS_IN_REQUEST
: la versión solo se quita si la ruta de acceso de solicitud original no contiene ninguna versión.ALWAYS_STRIP
: la versión siempre se quita, incluso si la ruta de acceso de solicitud original contiene la versión.
hostValue
: este parámetro se usa para reemplazar la partehost:port
del encabezado deLocation
de respuesta cuando se proporciona. Si no se proporciona, se usa el valor del encabezado de solicitudHost
.protocolsRegex
: una expresión regular válidaString
, con la que coincide el nombre del protocolo. Si no coincide, el filtro no funciona. El valor predeterminado eshttp|https|ftp|ftps
.locationHeaderName
La lista siguiente configura una fábrica RewriteLocationResponseHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,"
]
}
]
En este ejemplo, para un valor de solicitud de POST
api.example.com/some/object/name
, el valor del encabezado de respuesta Location
de object-service.prod.example.net/v2/some/object/id
se vuelve a escribir como api.example.com/some/object/id
.
RewritePath
La fábrica RewritePath
usa expresiones regulares de Java para una manera flexible de volver a escribir la ruta de acceso de la solicitud.
Esta fábrica acepta los siguientes parámetros de configuración:
regexp
replacement
La lista siguiente configura una fábrica RewritePath
:
[
{
"predicates": [
"Path=/red/**"
],
"filters": [
"RewritePath=/red/?(?<segment>.*), /$\\{segment}"
]
}
]
En este ejemplo, para una ruta de acceso de solicitud de /red/blue
, esta configuración establece la ruta de acceso a /blue
antes de realizar la solicitud de bajada.
RewriteResponseHeader
La fábrica RewriteResponseHeader
usa expresiones regulares de Java para una manera flexible de reescribir el valor del encabezado de respuesta.
Esta fábrica acepta los siguientes parámetros de configuración:
name
regexp
replacement
En el ejemplo siguiente se configura una fábrica RewriteResponseHeader
:
[
{
"predicates": [
"Path=/red/**"
],
"filters": [
"RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***"
]
}
]
En este ejemplo, para un valor de encabezado de /42?user=ford&password=omg!what&flag=true
, la configuración se establece en /42?user=ford&password=***&flag=true
después de realizar la solicitud de bajada.
SetPath
La fábrica SetPath
ofrece una manera sencilla de manipular la ruta de acceso de solicitud al permitir segmentos con plantilla de la ruta de acceso. Este filtro usa las plantillas de URI de Spring Framework y permite varios segmentos coincidentes.
Esta fábrica acepta el siguiente parámetro de configuración:
template
En el ejemplo siguiente se configura una fábrica SetPath
:
[
{
"predicates": [
"Path=/red/{segment}"
],
"filters": [
"SetPath=/{segment}"
]
}
]
En este ejemplo, para una ruta de acceso de solicitud de /red/blue
, esta configuración establece la ruta de acceso a /blue
antes de realizar la solicitud de bajada.
SetRequestHeader
La fábrica SetRequestHeader
reemplaza (en lugar de agregar) todos los encabezados por el nombre especificado.
Esta fábrica acepta los siguientes parámetros de configuración:
name
value
La lista siguiente configura una fábrica SetRequestHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"SetRequestHeader=X-Request-Red, Blue"
]
}
]
En este ejemplo, el servidor de bajada respondió con X-Request-Red:1234
y se reemplaza por X-Request-Red:Blue
.
La fábrica SetRequestHeader
tiene acceso a las variables de URI que se usan para buscar coincidencias con una ruta de acceso o host. Puede usar variables de URI en el valor y las variables se expanden en runtime.
En el ejemplo siguiente se configura una fábrica SetRequestHeader
que usa una variable:
[
{
"predicates": [
"Path=/api/{segment}"
],
"filters": [
"SetRequestHeader=foo, bar-{segment}"
]
}
]
SetResponseHeader
La fábrica SetResponseHeader
reemplaza (en lugar de agregar) todos los encabezados por el nombre especificado.
Esta fábrica acepta los siguientes parámetros de configuración:
name
value
La lista siguiente configura una fábrica SetResponseHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"SetResponseHeader=X-Response-Red, Blue"
]
}
]
En este ejemplo, el servidor de bajada respondió con X-Response-Red:1234
y se reemplaza por X-Response-Red:Blue
.
La fábrica SetResponseHeader
tiene acceso a las variables de URI que se usan para buscar coincidencias con una ruta de acceso o host. Puede usar variables de URI en el valor y las variables se expanden en runtime.
En el ejemplo siguiente se configura una fábrica SetResponseHeader
que usa una variable:
[
{
"predicates": [
"Path=/api/{segment}"
],
"filters": [
"SetResponseHeader=foo, bar-{segment}"
]
}
]
SetStatus
La fábrica SetStatus
configura el estado de respuesta de la solicitud del servidor.
Esta fábrica acepta el siguiente parámetro de configuración:
status
: un valor de SpringHttpStatus
válido, que puede ser un valor entero como404
o la representación de cadena de la enumeración, comoNOT_FOUND
.
La lista siguiente configura una fábrica SetStatus
:
[
{
"predicates": [
"Path=/experimental/**"
],
"filters": [
"SetStatus=UNAUTHORIZED"
]
},
{
"predicates": [
"Path=/unknown/**"
],
"filters": [
"SetStatus=401"
]
}
]
StripPrefix
La fábrica StripPrefix
quita el prefijo de la solicitud antes de enviarlo de bajada.
Esta fábrica acepta el siguiente parámetro de configuración:
parts
: número de partes de la ruta de acceso que se va a quitar de la solicitud antes de enviarlo de bajada. El valor predeterminado es 1.
En el ejemplo siguiente se configura una fábrica StripPrefix
:
[
{
"predicates": [
"Path=/name/**"
],
"filters": [
"StripPrefix=2"
]
}
]
En este ejemplo, se realiza una solicitud a través de la puerta de enlace para /name/blue/red
. La solicitud realizada a nameservice
aparece como nameservice/red
.
Volver a intentar
La fábrica Retry
determina el número de reintentos intentados.
Esta fábrica acepta los siguientes parámetros de configuración:
retries
: número de reintentos que se deben intentar.statuses
: códigos de estado HTTP que se deben reintentar, representados medianteorg.springframework.http.HttpStatus
.methods
: métodos HTTP que se deben reintentar, representados medianteorg.springframework.http.HttpMethod
.series
: códigos de estado HTTP que se deben reintentar, representados medianteorg.springframework.http.HttpStatus.Series
.exceptions
: lista de excepciones iniciadas que se deben reintentar.backoff
: retroceso exponencial configurado para los reintentos. Los reintentos se realizan después de un intervalo de retroceso defirstBackoff * (factor ^ n)
, donden
es la iteración. SimaxBackoff
está configurado, el retroceso máximo aplicado se limita amaxBackoff
. SibasedOnPreviousValue
es true, elbackoff
se calcula medianteprevBackoff * factor
.
Los siguientes valores predeterminados están configurados para el filtro de Retry
, cuando está habilitado:
retries
: tres veces.series
: serie 5XX.methods
: método GET.exceptions
:IOException
yTimeoutException
.backoff
: deshabilitado.
En el ejemplo siguiente se configura una fábrica Retry
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false"
]
}
]
RequestSize
La fábrica RequestSize
puede restringir que una solicitud llegue al servicio de bajada cuando el tamaño de la solicitud sea mayor que el límite permitido.
Esta fábrica acepta el siguiente parámetro de configuración:
maxSize
: un tipo deDataSize
en el que los valores se definen como un número seguido de un sufijo opcionalDataUnit
, comoKB
oMB
. El valor de sufijo predeterminado esB
para bytes. Es el límite de tamaño permitido de la solicitud definida en bytes.
En el ejemplo siguiente se configura una fábrica RequestSize
:
[
{
"predicates": [
"Path=/upload"
],
"filters": [
"RequestSize=5000000"
]
}
]
En este ejemplo, cuando se rechaza la solicitud debido al tamaño, la fábrica RequestSize
establece el estado de respuesta en 413 Payload Too Large
con otro encabezado errorMessage
.
En el ejemplo siguiente se muestra 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 fábrica TokenRelay
reenvía un token de acceso de OAuth2
a los recursos de nivel inferior. Este filtro se configura como un valor boolean
en la definición de ruta en lugar de un filtro explícito.
En el ejemplo siguiente se configura una fábrica TokenRelay
:
[
{
"predicates": [
"Path=/api/**"
],
"tokenRelay": true
}
]
Uso de filtros comerciales
Spring Cloud Gateway para Kubernetes también proporciona muchas fábricas GatewayFilter
personalizadas. En las siguientes secciones se describen estas fábricas.
AllowedRequestCookieCount
La fábrica AllowedRequestCookieCount
determina si se permite que una solicitud coincidente continúe en función del número de cookies.
Esta fábrica acepta el siguiente parámetro de configuración:
amount
: número de cookies permitidas.
En el ejemplo siguiente se configura una fábrica AllowedRequestCookieCount
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AllowedRequestCookieCount=2"
]
}
]
AllowedRequestHeadersCount
La fábrica AllowedRequestHeadersCount
determina si se permite que una solicitud coincidente continúe en función del número de encabezados.
Esta fábrica acepta el siguiente parámetro de configuración:
amount
: número de encabezados permitidos.
En el ejemplo siguiente se configura una fábrica AllowedRequestHeadersCount
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AllowedRequestHeadersCount=4"
]
}
]
AllowedRequestQueryParamsCount
La fábrica AllowedRequestQueryParamsCount
determina si se permite que una solicitud coincidente continúe en función de los parámetros de consulta numéricos.
Esta fábrica acepta el siguiente parámetro de configuración:
amount
: número de parámetros permitidos.
En el ejemplo siguiente se configura una fábrica AllowedRequestQueryParamsCount
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"AllowedRequestQueryParamsCount=3"
]
}
]
BasicAuth
La fábrica BasicAuth
agrega un encabezado BasicAuth
Authorization
a las solicitudes.
No hay parámetros para esta fábrica.
En el ejemplo siguiente se configura una fábrica BasicAuth
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"BasicAuth"
]
}
]
ClaimHeader
La fábrica ClaimHeader
copia datos de una notificación JWT en un encabezado HTTP.
Esta fábrica acepta los siguientes parámetros de configuración:
Claim name
: nombre que distingue mayúsculas de minúsculas de la notificación que se va a pasar.Header name
: el nombre del encabezado HTTP.
En el ejemplo siguiente se configura una fábrica ClaimHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"ClaimHeader=sub,X-Claim-Sub"
]
}
]
ClientCertificateHeader
La fábrica ClientCertificateHeader
valida el certificado de encabezado X-Forwarded-Client-Cert
.
Esta fábrica acepta los siguientes parámetros de configuración:
domain pattern
: el valor deX-Forwarded-Client-Cert
según la capacidad de Kubernetes de reconocer la CA del certificado de cliente.certificate fingerprint
(opcional): huella digital del certificado TLS/SSL.
En el ejemplo siguiente se configura una fábrica ClientCertificateHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"ClientCertificateHeader=*.example.com,sha-1:aa:bb:00:99"
]
}
]
CORS
La fábrica Cors
activa las validaciones de CORS en una ruta.
Esta fábrica acepta los siguientes parámetros de configuración que se organizan como pares clave-valor para las opciones de CORS:
allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns
En el ejemplo siguiente se configura una fábrica 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 fábrica JsonToXml
transforma el cuerpo de la respuesta JSON en cuerpo de respuesta XML.
Esta fábrica acepta el siguiente parámetro de configuración:
wrapper
: el nombre de etiqueta raíz de la respuesta XML si se requiere otra etiqueta raíz para generar XML válido. El valor predeterminado esresponse
.
En el ejemplo siguiente se configura una fábrica JsonToXml
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"JsonToXml=custom-response"
]
}
]
RateLimit
La fábrica RateLimit
determina si se permite que una solicitud coincidente continúe en función del volumen de solicitudes.
Esta fábrica acepta los siguientes parámetros de configuración:
request limit
: número máximo de solicitudes aceptadas durante la ventana.window duration
: duración de la ventana en milisegundos. Como alternativa, puede usar los sufijoss
,m
oh
para especificar la duración en segundos, minutos o horas.partition source
(opcional): la ubicación de la clave de partición (claim
,header
oIPs
).partition key
(opcional): valor usado para particionar contadores de solicitudes.
En el ejemplo siguiente se configura una fábrica RateLimit
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RateLimit=1,10s"
]
}
]
En los ejemplos siguientes se muestran otras configuraciones de 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 fábrica RestrictRequestHeaders
determina si se permite que una solicitud coincidente continúe en función de los encabezados.
Si hay encabezados HTTP que no tenga la configuración headerList
y que no distinguen mayúsculas de minúsculas, se devuelve una respuesta de 431 Forbidden error
al cliente.
Esta fábrica acepta el siguiente parámetro de configuración:
headerList
: lista sin distinción entre mayúsculas y minúsculas de nombres de encabezados permitidos.
En el ejemplo siguiente se configura una fábrica RestrictRequestHeaders
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RestrictRequestHeaders=Content-Type,x-request-temp"
]
}
]
RewriteAllResponseHeaders
La fábrica RewriteAllResponseHeaders
reescribe varios encabezados de respuesta a la vez.
Esta fábrica acepta los siguientes parámetros de configuración:
pattern to match
: expresión regular que se va a comparar con los valores de encabezado.replacement
: valor de reemplazo.
En el ejemplo siguiente se configura una fábrica RewriteAllResponseHeaders
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RewriteAllResponseHeaders=\\d,0"
]
}
]
RewriteResponseBody
La fábrica RewriteResponseBody
modifica el cuerpo de una respuesta.
Esta fábrica acepta los siguientes parámetros de configuración que se organizan como una lista separada por comas de pares clave-valor, donde cada par acepta el formulario pattern to match:replacement
:
pattern to match
: expresión regular que debe coincidir con el texto del cuerpo de la respuesta.replacement
: valor de reemplazo.
En el ejemplo siguiente se configura una fábrica RewriteResponseBody
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RewriteResponseBody=foo:bar,/path-one/:/path-two/"
]
}
]
RewriteJsonAttributesResponseBody
La fábrica RewriteJsonAttributesResponseBody
vuelve a escribir atributos JSON mediante la notación JSONPath
.
Esta fábrica acepta los siguientes parámetros de configuración que se organizan como una lista separada por comas de pares clave-valor, donde cada par acepta el formulario jsonpath:replacement
:
jsonpath
: la expresiónJSONPath
que se va a comparar con el cuerpo de la respuesta.replacement
: valor de reemplazo.
En el ejemplo siguiente se configura una fábrica RewriteJsonAttributesResponseBody
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"RewriteJsonAttributesResponseBody=slides[1].title:Welcome,date:11-11-2022"
]
}
]
Roles
La fábrica Roles
autoriza las solicitudes que contienen uno de los roles configurados.
Esta fábrica acepta el siguiente parámetro de configuración:
roles
: una lista separada por comas de roles autorizados.
En el ejemplo siguiente se configura una fábrica Roles
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"Roles=role_01,role_02"
]
}
]
Ámbitos
La fábrica Scopes
autoriza las solicitudes que contienen uno de los ámbitos de OAuth
configurados.
Esta fábrica acepta el siguiente parámetro de configuración:
scopes
: lista separada por comas de ámbitos deOAuth
autorizados.
En el ejemplo siguiente se configura una fábrica Scopes
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"Scopes=api.read,api.write,user"
]
}
]
StoreIpAddress
La fábrica StoreIPAddress
se usa solo para el desarrollo de extensiones y en el contexto de la aplicación.
Esta fábrica acepta el siguiente parámetro de configuración:
attribute name
: el nombre usado para almacenar la dirección IP como atributo de intercambio.
En el ejemplo siguiente se configura una fábrica StoreIPAddress
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"StoreIpAddress=ip"
]
}
]
Inicio de sesión SSO
La fábrica SSO login
redirige para autenticarse si no hay ningún token de autorización válido. Esta fábrica se configura como un valor boolean
en la definición de ruta en lugar de un filtro explícito.
En el ejemplo siguiente se configura una fábrica SSO login
:
[
{
"predicates": [
"Path=/api/**"
],
"ssoEnabled": true
}
]
StoreHeader
La fábrica StoreHeader
almacena un valor de encabezado en el contexto de la aplicación. Este filtro solo se usa para el desarrollo de extensiones.
Esta fábrica acepta los siguientes parámetros de configuración:
headers
: lista de encabezados que se van a comprobar. Se usa la primera encontrada.attribute name
: el nombre usado para almacenar el valor de encabezado como atributo de intercambio.
En el ejemplo siguiente se configura una fábrica StoreHeader
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"StoreHeader=x-tracing-header,custom-id,x-custom-id,tracingParam"
]
}
]
XmlToJson
La fábrica XmlToJson
transforma el cuerpo de la respuesta XML en cuerpo de respuesta JSON.
No hay parámetros para esta fábrica.
En el ejemplo siguiente se configura una fábrica XmlToJson
:
[
{
"predicates": [
"Path=/api/**"
],
"filters": [
"XmlToJson"
]
}
]