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

Artigo
08/28/2024

Observação

Os planos Básico, Standard e Enterprise serão preteridos a partir de meados de março de 2025, com um período de desativação de 3 anos. Recomendamos a transição para os Aplicativos de Contêiner do Azure. Para mais informações, confira o anúncio de desativação dos Aplicativos Spring do Azure.

O plano consumo e dedicado Standard será preterido a partir de 30 de setembro de 2024, com um desligamento completo após seis meses. Recomendamos a transição para os Aplicativos de Contêiner do Azure. Para mais informações, confira Migrar o plano dedicado e consumo Standard dos Aplicativos Spring do Azure para os Aplicativos de Contêiner do Azure.

Este artigo se aplica a: ❎ Básico/Padrão ✅ Enterprise

Este artigo explica como usar o Spring Cloud Gateway do VMware com o plano Enterprise dos Aplicativos Spring do Azure para rotear solicitações para seus aplicativos.

O Spring Cloud Gateway do VMware é um componente comercial do VMware Tanzu baseado no projeto do Spring Cloud Gateway de código aberto. O Spring Cloud Gateway cuida de preocupações variadas das equipes de desenvolvimento de API, como SSO (logon único), controle de acesso, limitação de taxa, resiliência, segurança, entre outros. É possível acelerar a entrega de APIs usando padrões nativos de nuvem modernos e qualquer linguagem de programação escolhida para o desenvolvimento delas.

O Spring Cloud Gateway do VMware 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 transporte de declarações JWT (Token Web JSON) autorizadas para serviços de aplicativo.
Autorização de certificado do cliente.
Abordagens de limitação de taxa.
Configuração do disjuntor.
Suporte para acessar serviços de aplicativo usando as credenciais de Autenticação Básica HTTP.

Para se integrar ao Portal de API do VMware Tanzu, o Spring Cloud Gateway do VMware gera a documentação do OpenAPI versão 3 automaticamente após qualquer alteração ou acréscimo na configuração de rota. Para obter mais informações, confira Usar o Portal de API do VMware Tanzu.

Pré-requisitos

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

Use filtros

Você usa filtros na configuração do Spring Cloud Gateway que funcionam 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 para negar acesso com base em um token de autorização.

Usar filtros de código aberto

O software de código aberto Spring Cloud Gateway inclui várias fábricas GatewayFilter usadas para criar filtros para rotas. As seções a seguir descrevem essas fábricas.

AddRequestHeader

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

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

name
value

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

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

A fábrica AddRequestHeader tem acesso às variáveis de URI usadas para fazer a correspondência com um caminho ou um host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em runtime.

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

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

AddRequestHeadersIfNotPresent

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

Essa 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 seguinte exemplo configura uma fábrica AddRequestHeadersIfNotPresent:

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

AddRequestParameter

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

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

name
value

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

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

A fábrica AddRequestParameter tem acesso às variáveis de URI usadas para fazer a correspondência com um caminho ou um host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em runtime.

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

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

AddResponseHeader

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

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

name
value

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

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

A fábrica AddResponseHeader tem acesso às variáveis de URI usadas para fazer a correspondência com um caminho ou um host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em runtime.

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

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

CircuitBreaker

A fábrica CircuitBreaker encapsula as rotas em um disjuntor.

Essa 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 para correspondência, em formato de número ou texto.
failure rate (opcional): o limite acima do qual o disjuntor é aberto. O valor padrão é 50%.
duration (opcional): o tempo de espera antes do novo fechamento dele. O valor padrão é 60 segundos.

O seguinte exemplo configura uma fábrica CircuitBreaker:

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

DeDupeResponseHeader

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

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

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

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

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

FallbackHeaders

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

Não há parâmetros para essa fábrica.

O seguinte exemplo configura uma fábrica FallbackHeaders com o tipo de exceção, a mensagem e (se disponível) o tipo de exceção de causa raiz e a mensagem que o filtro FallbackHeaders 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 os respectivos valores padrão):

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

JSONToGRPC

A fábrica JSONToGRPCFilter converte um conteúdo JSON em uma solicitação gRPC.

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

protoDescriptor: um arquivo de descritor proto.

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

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

Observação

Não há suporte para o parâmetro streaming.

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

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

LocalResponseCache

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

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

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

O seguinte exemplo configura uma fábrica LocalResponseCache:

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

MapRequestHeader

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

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

fromHeader
toHeader

Essa fábrica cria um 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, os valores dele serão aumentados com os novos valores.

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

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

PrefixPath

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

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

prefix

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

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

PreserveHostHeader

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

Não há parâmetros para essa fábrica.

O seguinte exemplo configura uma fábrica PreserveHostHeader:

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

RedirectTo

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

Essa 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 cabeçalho Location. Deve ser um URI válido. Para redirecionamentos relativos, você deve usar uri: no://op como o URI da definição de rota.

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

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

RemoveJsonAttributesResponseBody

A fábrica RemoveJsonAttributesResponseBody remove os atributos JSON e os respectivos valores dos corpos da resposta JSON.

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

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

O seguinte exemplo configura uma fábrica RemoveJsonAttributesResponseBody:

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

RemoveRequestHeader

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

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

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

A seguinte listagem configura uma fábrica RemoveRequestHeader que remove o cabeçalho X-Request-Foo antes de ele ser enviado downstream:

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

RemoveRequestParameter

A fábrica RemoveRequestParameter remove um parâmetro antes de ele ser enviado downstream.

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

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

O seguinte exemplo configura uma fábrica RemoveRequestParameter que remove o parâmetro red antes de ele ser enviado downstream:

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

RemoveResponseHeader

A fábrica RemoveResponseHeader remove um cabeçalho da resposta antes de ela ser retornada ao cliente do gateway.

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

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

A seguinte listagem configura uma fábrica RemoveResponseHeader que remove o cabeçalho X-Response-Foo da resposta antes de ela ser retornada ao cliente do gateway:

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

RequestHeaderSize

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

Essa 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 seguinte listagem configura uma fábrica RequestHeaderSize que envia um status 431 se o tamanho de qualquer cabeçalho de solicitação for maior que 1.000 bytes:

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

RewriteLocationResponseHeader

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

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

stripVersionMode: esse parâmetro tem os seguintes valores possíveis: NEVER_STRIP, AS_IN_REQUEST e ALWAYS_STRIP. O valor padrão é AS_IN_REQUEST.
- NEVER_STRIP: a versão não é removida, mesmo que o caminho da solicitação original não contenha nenhuma versão.
- AS_IN_REQUEST: a versão é removida somente se o caminho da solicitação original não contém nenhuma versão.
- ALWAYS_STRIP: a versão é sempre removida, mesmo que o caminho da solicitação original contenha a versão.
hostValue: esse parâmetro é usado para substituir a parte host:port do cabeçalho de resposta Location, quando fornecido. Se ele não for fornecido, o valor do cabeçalho da solicitação Host será usado.
protocolsRegex: um regex String válido, no qual é encontrada a correspondência do nome do protocolo. Se ele não for correspondente, o filtro não funcionará. O valor padrão é http|https|ftp|ftps.
locationHeaderName

A seguinte listagem configura uma fábrica RewriteLocationResponseHeader:

[
    {
        "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 valor object-service.prod.example.net/v2/some/object/id do cabeçalho de resposta Location é reescrito como api.example.com/some/object/id.

RewritePath

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

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

regexp
replacement

A seguinte listagem configura uma fábrica RewritePath:

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

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

RewriteResponseHeader

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

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

name
regexp
replacement

O seguinte exemplo configura uma fábrica RewriteResponseHeader:

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

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

SetPath

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

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

template

O seguinte exemplo configura uma fábrica SetPath:

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

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

SetRequestHeader

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

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

name
value

A seguinte listagem configura uma fábrica SetRequestHeader:

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

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

A fábrica SetRequestHeader tem acesso às variáveis de URI usadas para fazer a correspondência com um caminho ou um host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em runtime.

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

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

SetResponseHeader

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

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

name
value

A seguinte listagem configura uma fábrica SetResponseHeader:

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

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

A fábrica SetResponseHeader tem acesso às variáveis de URI usadas para fazer a correspondência com um caminho ou um host. Você pode usar variáveis de URI no valor e as variáveis são expandidas em runtime.

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

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

SetStatus

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

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

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

A seguinte listagem configura uma fábrica SetStatus:

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

StripPrefix

A fábrica StripPrefix remove o prefixo da solicitação antes de enviá-lo downstream.

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

parts: o número de partes no caminho a ser retirado da solicitação antes de enviá-la downstream. O valor padrão é 1.

O seguinte exemplo configura uma fábrica StripPrefix:

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

Neste exemplo, uma solicitação é feita por meio do gateway para /name/blue/red. A solicitação feita para nameservice é exibida como nameservice/red.

Repetir

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

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

retries: o número de tentativas que devem ser feitas.
statuses: os códigos de status HTTP que devem ser repetidos, representados com org.springframework.http.HttpStatus.
methods: os métodos HTTP que devem ser repetidos, representados com org.springframework.http.HttpMethod.
series: a série de códigos de status a ser repetida, representada com org.springframework.http.HttpStatus.Series.
exceptions: a lista de exceções geradas que devem ser repetidas.
backoff: a retirada exponencial configurada para as novas tentativas. As novas tentativas são feitas após um intervalo de retirada igual a firstBackoff * (factor ^ n), em que n é a iteração. Se maxBackoff estiver configurado, a retirada máxima aplicada será limitada a maxBackoff. Se basedOnPreviousValue for true, a backoff será calculada com prevBackoff * factor.

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

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

O seguinte exemplo configura uma fábrica Retry:

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

RequestSize

A fábrica RequestSize pode impedir que uma solicitação atinja o serviço downstream quando o tamanho da solicitação é maior que o limite permitido.

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

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

O seguinte exemplo configura uma fábrica RequestSize:

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

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

O seguinte exemplo mostra uma errorMessage:

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

TokenRelay

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

O seguinte exemplo configura uma fábrica TokenRelay:

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

Usar filtros comerciais

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

AllowedRequestCookieCount

A fábrica AllowedRequestCookieCount determina se uma solicitação correspondente tem permissão para prosseguir com base no número de cookies.

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

amount: o número de cookies permitidos.

O seguinte exemplo configura uma fábrica AllowedRequestCookieCount:

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

AllowedRequestHeadersCount

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

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

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

O seguinte exemplo configura uma fábrica AllowedRequestHeadersCount:

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

AllowedRequestQueryParamsCount

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

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

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

O seguinte exemplo configura uma fábrica AllowedRequestQueryParamsCount:

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

BasicAuth

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

Não há parâmetros para essa fábrica.

O seguinte exemplo configura uma fábrica BasicAuth:

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

ClaimHeader

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

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

Claim name: o nome diferenciado de maiúsculas e minúsculas da declaração a ser transmitida.
Header name: o nome do cabeçalho HTTP.

O seguinte exemplo configura uma fábrica ClaimHeader:

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

ClientCertificateHeader

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

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

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

O seguinte exemplo configura uma fábrica ClientCertificateHeader:

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

CORS

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

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

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

O seguinte exemplo configura uma 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

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

Essa 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 um XML válido. O valor padrão é response.

O seguinte exemplo configura uma fábrica JsonToXml:

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

RateLimit

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

Essa 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 os sufixos s, m ou h para especificar a duração em segundos, minutos ou horas.
partition source (opcional): o local da chave de partição (claim, header ou IPs).
partition key (opcional): o valor usado para particionar contadores de solicitação.

O seguinte exemplo configura uma fábrica RateLimit:

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

Os seguintes exemplos mostram outras configurações 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

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

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

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

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

O seguinte exemplo configura uma fábrica RestrictRequestHeaders:

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

RewriteAllResponseHeaders

A fábrica RewriteAllResponseHeaders reescreve vários cabeçalhos de resposta ao mesmo tempo.

Essa 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 seguinte exemplo configura uma fábrica RewriteAllResponseHeaders:

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

RewriteResponseBody

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

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

pattern to match: a expressão regular a ser correspondida ao texto no corpo da resposta.
replacement: o valor de substituição.

O seguinte exemplo configura uma fábrica RewriteResponseBody:

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

RewriteJsonAttributesResponseBody

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

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

jsonpath: a expressão JSONPath a ser correspondida ao corpo da resposta.
replacement: o valor de substituição.

O seguinte exemplo configura uma fábrica RewriteJsonAttributesResponseBody:

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

Funções

A fábrica Roles autoriza as solicitações que contêm uma das funções configuradas.

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

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

O seguinte exemplo configura uma fábrica Roles:

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

Escopos

A fábrica Scopes autoriza solicitações que contêm um dos escopos de OAuth configurados.

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

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

O seguinte exemplo configura uma fábrica Scopes:

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

StoreIpAddress

A fábrica StoreIPAddress é usada somente para desenvolvimento de extensão e no contexto do aplicativo.

Essa 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 seguinte exemplo configura uma fábrica StoreIPAddress:

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

A fábrica SSO login faz o redirecionamento para autenticação se não há nenhum token de autorização válido. Essa fábrica é configurada como um valor boolean na definição de rota em vez de um filtro explícito.

O seguinte exemplo configura uma fábrica SSO login:

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

StoreHeader

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

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

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

O seguinte exemplo configura uma fábrica StoreHeader:

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

XmlToJson

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

Não há parâmetros para essa fábrica.

O seguinte exemplo configura uma fábrica XmlToJson:

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

Compartilhar via

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

Pré-requisitos

Use filtros

Usar filtros de código aberto

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

Repetir

RequestSize

TokenRelay

Usar filtros comerciais

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

BasicAuth

ClaimHeader

ClientCertificateHeader

CORS

JsonToXml

RateLimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

Funções

Escopos

StoreIpAddress

SSO

StoreHeader

XmlToJson

Próximas etapas

Comentários

Recursos adicionais