Como usar os filtros de rota do VMware Spring Cloud Gateway com o plano do Azure Spring Apps Enterprise

Artigo
08/28/2024

Nota

Azure Spring Apps é o novo nome para o serviço Azure Spring Cloud. Embora o serviço tenha um novo nome, você verá o nome antigo em alguns lugares por um tempo enquanto trabalhamos para atualizar ativos, como capturas de tela, vídeos e diagramas.

Este artigo aplica-se a:❌ Basic/Standard ✔️ Enterprise

Este artigo explica como usar os filtros de rota do VMware Spring Cloud Gateway com o plano do Azure Spring Apps Enterprise para rotear solicitações para seus aplicativos.

O VMware Spring Cloud Gateway é um componente comercial do VMware Tanzu baseado no projeto de código aberto Spring Cloud Gateway. O Spring Cloud Gateway lida com preocupações transversais para as equipes de desenvolvimento de API, como logon único (SSO), controle de acesso, limitação de taxa, resiliência, segurança e muito mais. Você pode acelerar a entrega de API usando padrões modernos nativos da nuvem e qualquer linguagem de programação escolhida para o desenvolvimento de API.

O VMware Spring Cloud Gateway inclui os seguintes recursos:

Configuração de roteamento dinâmico, independente de aplicativos individuais que podem ser aplicados e alterados sem recompilação.
Filtros de rota de API comercial para transportar a reivindicação autorizada de JSON Web Token (JWT) para serviços de aplicativo.
Autorização de certificado de cliente.
Abordagens de limitação de taxas.
Configuração do disjuntor.
Suporte para acessar serviços de aplicativos por meio de credenciais de autenticação básica HTTP.

Para integrar com o API Portal for VMware Tanzu, o VMware Spring Cloud Gateway gera automaticamente a documentação do OpenAPI versão 3 após quaisquer adições ou alterações na configuração de rota. Para obter mais informações, consulte Usar o API Portal for VMware Tanzu.

Pré-requisitos

Uma instância de serviço de plano do Azure Spring Apps Enterprise já provisionada com o Spring Cloud Gateway habilitado. Para obter mais informações, consulte Guia de início rápido: criar e implantar aplicativos no Azure Spring Apps usando o plano Enterprise.
CLI do Azure versão 2.0.67 ou posterior. Use o seguinte comando para instalar a extensão Azure Spring Apps: az extension add --name spring.

Utilizar filtros

Você usa filtros na configuração do Spring Cloud Gateway para agir na solicitação de entrada ou na resposta de saída para uma configuração de rota.

Por exemplo, você pode usar um filtro para adicionar um cabeçalho HTTP ou negar acesso com base em um token de autorização.

Usar filtros de código aberto

O Spring Cloud Gateway OSS inclui várias GatewayFilter fábricas usadas para criar filtros para rotas. As seções a seguir descrevem essas fábricas.

AddRequestHeader

A AddRequestHeader fábrica adiciona um cabeçalho aos cabeçalhos da solicitação downstream para todas as solicitações correspondentes.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
value

O exemplo a seguir configura uma AddRequestHeader fábrica que adiciona o cabeçalho X-Request-red:blue aos cabeçalhos da solicitação downstream para todas as solicitações correspondentes:

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

A AddRequestHeader fábrica tem acesso às variáveis de URI usadas para corresponder a um caminho ou host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em tempo de execução.

O exemplo a seguir configura uma AddRequestHeader fábrica que usa uma variável:

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

AddRequestHeadersIfNotPresent

A AddRequestHeadersIfNotPresent fábrica adiciona cabeçalhos se eles não estiverem presentes na solicitação original.

Esta fábrica aceita o seguinte parâmetro de configuração:

headers: Uma lista separada por vírgulas de pares chave-valor (nome do cabeçalho, valor do cabeçalho).

O exemplo a seguir configura uma AddRequestHeadersIfNotPresent fábrica:

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

AddRequestParameter

A AddRequestParameter fábrica adiciona um parâmetro à cadeia de caracteres de consulta da solicitação downstream para todas as solicitações correspondentes.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
value

O exemplo a seguir configura uma AddRequestParameter fábrica que adiciona um red=blue parâmetro à cadeia de caracteres de consulta da solicitação downstream para todas as solicitações correspondentes:

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

A AddRequestParameter fábrica tem acesso às variáveis de URI usadas para corresponder a um caminho ou host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em tempo de execução.

O exemplo a seguir configura uma AddRequestParameter fábrica que usa uma variável:

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

AddResponseHeader

A AddResponseHeader fábrica adiciona um cabeçalho aos cabeçalhos da resposta downstream para todas as solicitações correspondentes.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
value

O exemplo a seguir configura uma AddResponseHeader fábrica que adiciona um X-Response-Red:Blue cabeçalho aos cabeçalhos da resposta downstream para todas as solicitações correspondentes:

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

A AddResponseHeader fábrica tem acesso às variáveis de URI usadas para corresponder a um caminho ou host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em tempo de execução.

O exemplo a seguir configura uma AddResponseHeader fábrica que usa uma variável:

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

Disjuntor

A CircuitBreaker fábrica envolve rotas em um disjuntor.

Esta fábrica aceita os seguintes parâmetros de configuração:

name: O nome do disjuntor.
fallbackUri: O URI de redirecionamento, que pode ser uma rota local ou um manipulador externo.
status codes (opcional): A lista separada por dois pontos de códigos de status a serem correspondentes, em formato de número ou texto.
failure rate (opcional): O limiar acima do qual o disjuntor se abre. O valor padrão é 50%.
duration (opcional): O tempo de espera antes de fechar novamente. O valor padrão é 60 segundos.

O exemplo a seguir configura uma CircuitBreaker fábrica:

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

DeDupeResponseHeader

A DeDupeResponseHeader fábrica remove valores duplicados de cabeçalhos de resposta.

Esta fábrica aceita os seguintes parâmetros de configuração:

name: Uma lista separada por espaços de nomes de cabeçalho.
strategy (opcional): Os valores aceites são RETAIN_FIRST, RETAIN_LAST, e RETAIN_UNIQUE. O valor predefinido é RETAIN_FIRST.

O exemplo a seguir configura uma DeDupeResponseHeader fábrica que remove valores duplicados e Access-Control-Allow-Origin cabeçalhos de resposta quando ambos os valores são adicionados pela lógica CORS do Access-Control-Allow-Credentials gateway e pela lógica downstream:

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

FallbackHeaders

A FallbackHeaders fábrica adiciona qualquer exceção de disjuntor a um cabeçalho. Este filtro requer o CircuitBreaker uso do filtro em outra rota.

Não existem parâmetros para esta fábrica.

O exemplo a seguir configura uma FallbackHeaders fábrica com o tipo de exceção, mensagem e (se disponível) tipo de exceção de causa raiz e mensagem que o FallbackHeaders filtro adiciona à solicitação:

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

Você pode substituir os nomes dos cabeçalhos na configuração definindo os valores dos seguintes parâmetros (mencionados com seus valores padrão):

executionExceptionTypeHeaderName ("Execução-Exceção-Tipo")
executionExceptionMessageHeaderName ("Execution-Exception-Message")
rootCauseExceptionTypeHeaderName ("Causa-raiz-Exceção-Tipo")
rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

JSONToGRPC

A JSONToGRPCFilter fábrica converte uma carga JSON em uma solicitação gRPC.

Esta fábrica aceita o seguinte parâmetro de configuração:

protoDescriptor: Um arquivo descritor proto.

Você pode gerar esse arquivo usando protoc e especificando o --descriptor_set_out sinalizador, conforme mostrado no exemplo a seguir:

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

Nota

O streaming parâmetro não é suportado.

O exemplo a seguir configura uma JSONToGRPCFilter fábrica usando a saída de protoc:

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

LocalResponseCache

A LocalResponseCache fábrica substitui a configuração do cache de resposta local para rotas específicas quando o cache global é ativado.

Esta fábrica aceita os seguintes parâmetros de configuração:

size: O tamanho máximo permitido das entradas de cache para esta rota antes do início da remoção do cache (em KB, MB e GB).
timeToLive: A vida útil permitida de uma entrada de cache antes da expiração. Use o sufixo s de duração por segundos, m minutos ou h horas.

O exemplo a seguir configura uma LocalResponseCache fábrica:

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

MapRequestHeader

A MapRequestHeader fábrica adiciona um cabeçalho à solicitação downstream com valores atualizados do cabeçalho da solicitação HTTP de entrada.

Esta fábrica aceita os seguintes parâmetros de configuração:

fromHeader
toHeader

Essa fábrica cria um novo cabeçalho nomeado (toHeader), e o valor é extraído de um cabeçalho nomeado existente (fromHeader) da solicitação HTTP de entrada. Se o cabeçalho de entrada não existir, o filtro não terá efeito. Se o novo cabeçalho nomeado já existir, seus valores serão aumentados com os novos valores.

O exemplo a seguir configura uma MapRequestHeader fábrica que adiciona o X-Request-Red:<values> cabeçalho à solicitação downstream com valores atualizados do cabeçalho da solicitação Blue HTTP de entrada:

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

PrefixPath

A PrefixPath fábrica adiciona um prefixo ao caminho de todas as solicitações.

Esta fábrica aceita o seguinte parâmetro de configuração:

prefix

O exemplo a seguir configura uma PrefixPath fábrica que adiciona o prefixo /api ao caminho de todas as solicitações, para que uma solicitação seja /catalog enviada para /api/catalog:

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

PreserveHostHeader

A PreserveHostHeader fábrica define um atributo de solicitação que o filtro de roteamento inspeciona para determinar se deve enviar o cabeçalho de host original ou o cabeçalho de host determinado pelo cliente HTTP.

Não existem parâmetros para esta fábrica.

O exemplo a seguir configura uma PreserveHostHeader fábrica:

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

RedirectTo

A RedirectTo fábrica adiciona um redirecionamento ao URL original.

Esta fábrica aceita os seguintes parâmetros de configuração:

status: Um código HTTP de redirecionamento da série 300, como 301.
url: O valor do Location cabeçalho. Deve ser um URI válido. Para redirecionamentos relativos, você deve usar uri: no://op como o URI da sua definição de rota.

O exemplo a seguir configura uma RedirectTo fábrica que envia um status 302 com um Location:https://acme.org cabeçalho para executar um redirecionamento:

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

RemoveJsonAttributesResponseBody

A RemoveJsonAttributesResponseBody fábrica remove os atributos JSON e seus valores dos corpos de resposta JSON.

Esta fábrica aceita os seguintes parâmetros de configuração:

attribute names: Uma lista separada por vírgulas dos nomes dos atributos a serem removidos de uma resposta JSON.
delete recursively (opcional, booleano): uma configuração que remove os atributos somente no nível raiz (false), ou recursivamente (true). O valor predefinido é false.

O exemplo a seguir configura uma RemoveJsonAttributesResponseBody fábrica:

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

RemoveRequestHeader

A RemoveRequestHeader fábrica remove um cabeçalho da solicitação a jusante.

Esta fábrica aceita o seguinte parâmetro de configuração:

name: O nome do cabeçalho a ser removido.

A listagem a seguir configura uma RemoveRequestHeader fábrica que remove o X-Request-Foo cabeçalho antes que ele seja enviado downstream:

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

RemoveRequestParameter

A RemoveRequestParameter fábrica remove um parâmetro antes que ele seja enviado para jusante.

Esta fábrica aceita o seguinte parâmetro de configuração:

name: O nome do parâmetro de consulta a ser removido.

O exemplo a seguir configura uma RemoveRequestParameter fábrica que remove o red parâmetro antes que ele seja enviado downstream:

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

RemoveResponseHeader

A RemoveResponseHeader fábrica remove um cabeçalho da resposta antes que ele seja retornado ao cliente de gateway.

Esta fábrica aceita o seguinte parâmetro de configuração:

name: O nome do cabeçalho a ser removido.

A listagem a seguir configura uma RemoveResponseHeader fábrica que remove o X-Response-Foo cabeçalho da resposta antes que ele seja retornado ao cliente de gateway:

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

RequestHeaderSize

A RequestHeaderSize fábrica determina o tamanho do cabeçalho da solicitação.

Esta fábrica aceita os seguintes parâmetros de configuração:

maxSize: O tamanho máximo de dados permitido pelo cabeçalho da solicitação, incluindo chave e valor.
errorHeaderName: O nome do cabeçalho de resposta que contém uma mensagem de erro. Por padrão, o nome do cabeçalho de resposta é errorMessage.

A listagem a seguir configura uma RequestHeaderSize fábrica que envia um status 431 se o tamanho de qualquer cabeçalho de solicitação for maior que 1000 bytes:

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

RewriteLocationResponseHeader

A RewriteLocationResponseHeader fábrica modifica o valor do cabeçalho de Location resposta, geralmente para se livrar de detalhes específicos do back-end.

Esta fábrica aceita os seguintes parâmetros de configuração:

stripVersionMode: Este parâmetro tem os seguintes valores possíveis: NEVER_STRIP, AS_IN_REQUEST, e ALWAYS_STRIP. O valor predefinido é AS_IN_REQUEST.
- NEVER_STRIP: A versão não é removida, mesmo que o caminho de solicitação original não contenha versão.
- AS_IN_REQUEST: A versão será removida somente se o caminho de solicitação original não contiver versão.
- ALWAYS_STRIP: A versão é sempre removida, mesmo que o caminho de solicitação original contenha versão.
hostValue: Este parâmetro é usado para substituir a host:port parte do cabeçalho de resposta Location quando fornecido. Se não for fornecido, o Host valor do cabeçalho da solicitação será usado.
protocolsRegex: Um regex Stringválido , com o qual o nome do protocolo é correspondido. Se não corresponder, o filtro não funciona. O valor predefinido é http|https|ftp|ftps.
locationHeaderName

A listagem a seguir configura uma RewriteLocationResponseHeader fábrica:

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

Neste exemplo, para um valor de solicitação de POST api.example.com/some/object/name, o Location valor do cabeçalho de resposta de object-service.prod.example.net/v2/some/object/id é reescrito como api.example.com/some/object/id.

RewritePath

A RewritePath fábrica usa expressões regulares Java para uma maneira flexível de reescrever o caminho da solicitação.

Esta fábrica aceita os seguintes parâmetros de configuração:

regexp
replacement

A listagem a seguir configura uma RewritePath fábrica:

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

Neste exemplo, para um caminho de solicitação de , essa configuração define o caminho para /blue antes de /red/bluefazer a solicitação downstream.

RewriteResponseHeader

A RewriteResponseHeader fábrica usa expressões regulares Java para uma maneira flexível de reescrever o valor do cabeçalho de resposta.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
regexp
replacement

O exemplo a seguir configura uma RewriteResponseHeader fábrica:

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

Neste exemplo, para um valor de cabeçalho de , a configuração é definida como /42?user=ford&password=***&flag=true depois de /42?user=ford&password=omg!what&flag=truefazer a solicitação downstream.

SetPath

A SetPath fábrica oferece uma maneira simples de manipular o caminho de solicitação, permitindo segmentos de modelo do caminho. Esse filtro usa os modelos de URI do Spring Framework e permite vários segmentos correspondentes.

Esta fábrica aceita o seguinte parâmetro de configuração:

template

O exemplo a seguir configura uma SetPath fábrica:

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

Neste exemplo, para um caminho de solicitação de , essa configuração define o caminho para /blue antes de /red/bluefazer a solicitação downstream.

SetRequestHeader

A SetRequestHeader fábrica substitui (em vez de adicionar) todos os cabeçalhos pelo nome próprio.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
value

A listagem a seguir configura uma SetRequestHeader fábrica:

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

Neste exemplo, o servidor downstream respondeu com X-Request-Red:1234, e foi substituído por X-Request-Red:Blue.

A SetRequestHeader fábrica tem acesso às variáveis de URI usadas para corresponder a um caminho ou host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em tempo de execução.

O exemplo a seguir configura uma SetRequestHeader fábrica que usa uma variável:

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

SetResponseHeader

A SetResponseHeader fábrica substitui (em vez de adicionar) todos os cabeçalhos pelo nome próprio.

Esta fábrica aceita os seguintes parâmetros de configuração:

name
value

A listagem a seguir configura uma SetResponseHeader fábrica:

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

Neste exemplo, o servidor downstream respondeu com X-Response-Red:1234, e foi substituído por X-Response-Red:Blue.

A SetResponseHeader fábrica tem acesso às variáveis de URI usadas para corresponder a um caminho ou host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em tempo de execução.

O exemplo a seguir configura uma SetResponseHeader fábrica que usa uma variável:

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

SetStatus

A SetStatus fábrica configura o status de resposta da solicitação do servidor.

Esta fábrica aceita o seguinte parâmetro de configuração:

status: Um valor Spring HttpStatus válido, que pode ser um valor inteiro como 404, ou a representação de cadeia de caracteres da enumeração, como NOT_FOUND.

A listagem a seguir configura uma SetStatus fábrica:

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

StripPrefix

A StripPrefix fábrica remove o prefixo da solicitação antes de enviá-la para jusante.

Esta fábrica aceita o seguinte parâmetro de configuração:

parts: O número de partes no caminho a serem removidas da solicitação antes de enviá-la para jusante. O valor predefinido é 1.

O exemplo a seguir configura uma StripPrefix fábrica:

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

Neste exemplo, uma solicitação é feita por meio do gateway para /name/blue/red. O pedido feito aparece nameservice como nameservice/red.

Tentar novamente

A Retry fábrica determina o número de novas tentativas tentadas.

Esta fábrica aceita os seguintes parâmetros de configuração:

retries: O número de tentativas que devem ser tentadas.
statuses: Os códigos de status HTTP que devem ser repetidos, representados usando org.springframework.http.HttpStatus.
methods: Os métodos HTTP que devem ser repetidos, representados usando org.springframework.http.HttpMethod.
series: A série de códigos de status a serem repetidos, representada usando org.springframework.http.HttpStatus.Series.
exceptions: A lista de exceções lançadas que devem ser repetidas.
backoff: O backoff exponencial configurado para as tentativas. As novas tentativas são realizadas após um intervalo de backoff de firstBackoff * (factor ^ n), onde n é a iteração. Se maxBackoff estiver configurado, o backoff máximo aplicado será limitado a maxBackoff. Se basedOnPreviousValue for verdadeiro, o backoff é calculado usando prevBackoff * factor.

Os seguintes padrões são configurados para o filtro, quando habilitados Retry :

retries: três vezes.
series: Série 5XX.
methods: Método GET.
exceptions: IOException e TimeoutException.
backoff: deficiente.

O exemplo a seguir configura uma Retry fábrica:

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

RequestSize

A RequestSize fábrica pode impedir que uma solicitação chegue ao serviço a jusante quando o tamanho da solicitação for maior do que o limite permitido.

Esta fábrica aceita o seguinte parâmetro de configuração:

maxSize: Um DataSize tipo em que os valores são definidos como um número seguido por um sufixo opcional DataUnit , como KB ou MB. O valor de sufixo padrão é B para bytes. É o limite de tamanho permitido da solicitação definida em bytes.

O exemplo a seguir configura uma RequestSize fábrica:

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

Neste exemplo, quando a solicitação é rejeitada devido ao tamanho, a RequestSize fábrica define o status da resposta como 413 Payload Too Large com outro cabeçalho errorMessage.

O exemplo a seguir mostra um errorMessagearquivo :

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

TokenRelay

A TokenRelay fábrica encaminha um OAuth2 token de acesso para recursos downstream. Esse filtro é configurado como um boolean valor na definição de rota em vez de um filtro explícito.

O exemplo a seguir configura uma TokenRelay fábrica:

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

Utilize filtros comerciais

O Spring Cloud Gateway para Kubernetes também fornece muitas fábricas personalizadas GatewayFilter . As seções a seguir descrevem essas fábricas.

AllowedRequestCookieCount

A AllowedRequestCookieCount fábrica determina se um pedido de correspondência pode prosseguir com base no número de cookies.

Esta fábrica aceita o seguinte parâmetro de configuração:

amount: O número de cookies permitidos.

O exemplo a seguir configura uma AllowedRequestCookieCount fábrica:

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

AllowedRequestHeadersCount

A AllowedRequestHeadersCount fábrica determina se uma solicitação correspondente pode prosseguir com base no número de cabeçalhos.

Esta fábrica aceita o seguinte parâmetro de configuração:

amount: O número de cabeçalhos permitidos.

O exemplo a seguir configura uma AllowedRequestHeadersCount fábrica:

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

AllowedRequestQueryParamsCount

A AllowedRequestQueryParamsCount fábrica determina se uma solicitação correspondente pode prosseguir com base nos parâmetros de consulta de número.

Esta fábrica aceita o seguinte parâmetro de configuração:

amount: O número de parâmetros permitidos.

O exemplo a seguir configura uma AllowedRequestQueryParamsCount fábrica:

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

BasicAuth

A BasicAuth fábrica adiciona um BasicAuth Authorization cabeçalho às solicitações.

Não existem parâmetros para esta fábrica.

O exemplo a seguir configura uma BasicAuth fábrica:

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

ClaimHeader

A ClaimHeader fábrica copia dados de uma declaração JWT para um cabeçalho HTTP.

Esta fábrica aceita os seguintes parâmetros de configuração:

Claim name: O nome sensível a maiúsculas e minúsculas da reivindicação a ser aprovada.
Header name: O nome do cabeçalho HTTP.

O exemplo a seguir configura uma ClaimHeader fábrica:

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

ClientCertificateHeader

A ClientCertificateHeader fábrica valida o certificado de X-Forwarded-Client-Cert cabeçalho.

Esta fábrica aceita os seguintes parâmetros de configuração:

domain pattern: O X-Forwarded-Client-Cert valor de acordo com a capacidade do Kubernetes de reconhecer a CA do certificado do cliente.
certificate fingerprint(opcional): A impressão digital do certificado TLS/SSL.

O exemplo a seguir configura uma ClientCertificateHeader fábrica:

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

Cors

A Cors fábrica ativa as validações CORS em uma rota.

Esta fábrica aceita os seguintes parâmetros de configuração que são organizados como pares chave-valor para opções CORS:

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

O exemplo a seguir configura uma Cors fábrica:

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

JsonToXml

A JsonToXml fábrica transforma o corpo da resposta JSON em corpo de resposta XML.

Esta fábrica aceita o seguinte parâmetro de configuração:

wrapper: O nome da marca raiz para a resposta XML se outra marca raiz for necessária para gerar XML válido. O valor predefinido é response.

O exemplo a seguir configura uma JsonToXml fábrica:

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

RateLimit

A RateLimit fábrica determina se uma solicitação correspondente pode prosseguir com base no volume da solicitação.

Esta fábrica aceita os seguintes parâmetros de configuração:

request limit: O número máximo de solicitações aceitas durante a janela.
window duration: A duração da janela em milissegundos. Como alternativa, você pode usar o s, m ou h sufixos para especificar a duração em segundos, minutos ou horas.
partition source (opcional): A localização da chave de partição (claim, header, ou IPs).
partition key (opcional): O valor usado para particionar contadores de solicitação.

O exemplo a seguir configura uma RateLimit fábrica:

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

Os exemplos a seguir mostram outras RateLimit configurações:

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

A RestrictRequestHeaders fábrica determina se uma solicitação correspondente pode prosseguir com base nos cabeçalhos.

Se houver cabeçalhos HTTP que não estejam na configuração que não diferencia maiúsculas de minúsculas headerList , uma resposta de será retornada 431 Forbidden error ao cliente.

Esta fábrica aceita o seguinte parâmetro de configuração:

headerList: A lista de nomes de cabeçalhos permitidos que não diferencia maiúsculas de minúsculas.

O exemplo a seguir configura uma RestrictRequestHeaders fábrica:

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

RewriteAllResponseHeaders

A RewriteAllResponseHeaders fábrica reescreve vários cabeçalhos de resposta de uma só vez.

Esta fábrica aceita os seguintes parâmetros de configuração:

pattern to match: A expressão regular a ser correspondida aos valores de cabeçalho.
replacement: O valor de substituição.

O exemplo a seguir configura uma RewriteAllResponseHeaders fábrica:

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

RewriteResponseBody

A RewriteResponseBody fábrica modifica o corpo de uma resposta.

Esta fábrica aceita os seguintes parâmetros de configuração que são organizados como uma lista separada por vírgulas de pares chave-valor, onde cada par aceita o formulário pattern to match:replacement:

pattern to match: A expressão regular para corresponder ao texto no corpo da resposta.
replacement: O valor de substituição.

O exemplo a seguir configura uma RewriteResponseBody fábrica:

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

RewriteJsonAttributesResponseBody

A RewriteJsonAttributesResponseBody fábrica reescreve atributos JSON usando JSONPath notação.

Esta fábrica aceita os seguintes parâmetros de configuração que são organizados como uma lista separada por vírgulas de pares chave-valor, onde cada par aceita o formulário jsonpath:replacement:

jsonpath: A JSONPath expressão para corresponder ao corpo da resposta.
replacement: O valor de substituição.

O exemplo a seguir configura uma RewriteJsonAttributesResponseBody fábrica:

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

Funções

A Roles fábrica autoriza solicitações que contenham uma das funções configuradas.

Esta fábrica aceita o seguinte parâmetro de configuração:

roles: Uma lista separada por vírgulas de funções autorizadas.

O exemplo a seguir configura uma Roles fábrica:

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

Âmbitos

A Scopes fábrica autoriza solicitações que contenham um dos escopos configurados OAuth .

Esta fábrica aceita o seguinte parâmetro de configuração:

scopes: Uma lista separada por vírgulas de escopos autorizados OAuth .

O exemplo a seguir configura uma Scopes fábrica:

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

StoreIpAddress

A StoreIPAddress fábrica é usada apenas para o desenvolvimento de extensão e no contexto da aplicação.

Esta fábrica aceita o seguinte parâmetro de configuração:

attribute name: O nome usado para armazenar o IP como um atributo de troca.

O exemplo a seguir configura uma StoreIPAddress fábrica:

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

A SSO login fábrica redireciona para autenticar se não houver um token de autorização válido. Esta fábrica é configurada como um boolean valor na definição de rota em vez de um filtro explícito.

O exemplo a seguir configura uma SSO login fábrica:

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

StoreHeader

A StoreHeader fábrica armazena um valor de cabeçalho no contexto do aplicativo. Este filtro é usado apenas para desenvolvimento de extensão.

Esta fábrica aceita os seguintes parâmetros de configuração:

headers: Uma lista de cabeçalhos a verificar. O primeiro encontrado é usado.
attribute name: O nome usado para armazenar o valor do cabeçalho como um atributo de troca.

O exemplo a seguir configura uma StoreHeader fábrica:

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

XmlToJson

A XmlToJson fábrica transforma o corpo da resposta XML em corpo de resposta JSON.

Não existem parâmetros para esta fábrica.

O exemplo a seguir configura uma XmlToJson fábrica:

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

Partilhar via

Como usar os filtros de rota do VMware Spring Cloud Gateway com o plano do Azure Spring Apps Enterprise

Pré-requisitos

Utilizar filtros

Usar filtros de código aberto

AddRequestHeader

AddRequestHeadersIfNotPresent

AddRequestParameter

AddResponseHeader

Disjuntor

DeDupeResponseHeader

FallbackHeaders

JSONToGRPC

LocalResponseCache

MapRequestHeader

PrefixPath

PreserveHostHeader

RedirectTo

RemoveJsonAttributesResponseBody

RemoveRequestHeader

RemoveRequestParameter

RemoveResponseHeader

RequestHeaderSize

RewriteLocationResponseHeader

RewritePath

RewriteResponseHeader

SetPath

SetRequestHeader

SetResponseHeader

SetStatus

StripPrefix

Tentar novamente

RequestSize

TokenRelay

Utilize filtros comerciais

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

BasicAuth

ClaimHeader

ClientCertificateHeader

Cors

JsonToXml

RateLimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

Funções

Âmbitos

StoreIpAddress

Login SSO

StoreHeader

XmlToJson

Próximos passos

Comentários

Recursos adicionais