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

Artigo
02/02/2024

Observação

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

Este artigo se aplica a(o):❌ Básico/Standard ✔️ Enterprise

Este artigo explica como usar filtros de rota do VMware Spring Cloud Gateway com o plano do Azure Spring Apps Enterprise 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 transportar declaração JWT (JSON Web Token) autorizada 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 integração 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 de 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 do plano 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 dos Aplicativos Spring do Azure: az extension add --name spring.

Use filtros

Use filtros na configuração do Spring Cloud Gateway para agir na solicitação de entrada ou na resposta de saída a 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 fábrica que usa uma AddRequestHeader 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 fábrica que usa uma AddRequestParameter 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 fábrica que usa uma AddResponseHeader variável:

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

CircuitBreaker

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 correspondidos, 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 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ço de nomes de cabeçalho.
strategy (opcional): Os valores aceitos são RETAIN_FIRST, RETAIN_LASTe RETAIN_UNIQUE. O valor padrão é RETAIN_FIRST.

O exemplo a seguir configura uma DeDupeResponseHeader fábrica que remove valores duplicados de cabeçalhos e Access-Control-Allow-CredentialsAccess-Control-Allow-Origin resposta quando ambos os valores são adicionados pela lógica CORS do 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. Esse filtro requer o CircuitBreaker uso do filtro em outra rota.

Não há 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 ("Execution-Exception-Type")
executionExceptionMessageHeaderName ("Execução-Exceção-Mensagem")
rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")
rootCauseExceptionMessageHeaderName ("Mensagem-Causa-Exceção")

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

Observação

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 essa rota antes do início da remoção de 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 por minutos ou h por 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 () e o valor é extraído de um cabeçalho nomeado existente (toHeaderfromHeader) 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 Blue solicitação 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 fábrica que adiciona o prefixo /api ao caminho de todas as solicitações, para que uma PrefixPath solicitação para seja enviada para /catalog/api/catalog:

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

PreserveHostHeader

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

Não há 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 à 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 cabeçalho para executar um Location:https://acme.org 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 () ou recursivamente (falsetrue). O valor padrão é 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 downstream.

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 a 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 da 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 Location valor do cabeçalho de 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_REQUESTe ALWAYS_STRIP. O valor padrão é AS_IN_REQUEST.
- NEVER_STRIP: A versão não é removida, mesmo se o caminho de solicitação original não contiver nenhuma versão.
- AS_IN_REQUEST: A versão será removida somente se o caminho da solicitação original não contiver nenhuma versão.
- ALWAYS_STRIP: A versão é sempre removida, mesmo se o caminho de solicitação original contiver 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 , contra o qual o nome do protocolo é correspondido. Se não corresponder, o filtro não funciona. O valor padrão é 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 , o Location valor de cabeçalho de object-service.prod.example.net/v2/some/object/idPOSTapi.example.com/some/object/nameresposta é 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 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.

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 com o nome fornecido.

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 fábrica que usa uma SetRequestHeader 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 com o nome fornecido.

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 fábrica que usa uma SetResponseHeader 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 , ou a representação de cadeia de caracteres da enumeração, como 404NOT_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á-lo downstream.

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

parts: O número de partes no caminho para remover da solicitação antes de enviá-la a jusante. O valor padrão é 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. A solicitação feita para nameservice aparece como nameservice/red.

Repetir

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

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, representados usando org.springframework.http.HttpStatus.Series.
exceptions: A lista de exceções lançadas que devem ser repetidas.
backoff: O recuo exponencial configurado para as tentativas. As tentativas são executadas após um intervalo de recuo de firstBackoff * (factor ^ n), onde n é a iteração. Se maxBackoff estiver configurado, o recuo máximo aplicado será limitado a maxBackoff. Se basedOnPreviousValue for true, o backoff é calculado usando prevBackoff * factor.

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

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

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 restringir que uma solicitação chegue ao serviço downstream 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 definido 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 valor na definição de rota em vez de um boolean filtro explícito.

O exemplo a seguir configura uma TokenRelay fábrica:

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

Usar filtros comerciais

O Spring Cloud Gateway for 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 uma solicitação correspondente 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 tem permissão para 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 tem permissão para 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 BasicAuthAuthorization cabeçalho às solicitações.

Não há 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 em 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 declaraçã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 X-Forwarded-Client-Cert certificado de 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.

Essa 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 da 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 padrão é 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 tem permissão para prosseguir com base no volume de 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 os sufixos s, m ou para especificar a duração em segundos, minutos ou h horas.
partition source (opcional): O local da chave de partição (claim, headerou 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 tem permissão para prosseguir com base nos cabeçalhos.

Se houver cabeçalhos HTTP que não estejam na configuração que diferencia headerList maiúsculas de minúsculas, 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.

Essa 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.

Essa 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 a ser comparada com o 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"
        ]
    }
]

Direitos

A Roles fábrica autoriza solicitações que contêm 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"
        ]
    }
]

Escopos

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 desenvolvimento de extensão e no contexto do aplicativo.

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 nenhum token de autorização válido. Essa fábrica é configurada como um valor na definição de rota em vez de um boolean 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. Esse 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 serem verificados. 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 no corpo da resposta JSON.

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

O exemplo a seguir configura uma XmlToJson fábrica:

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

Compartilhar via

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

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

Direitos

Escopos

StoreIpAddress

Login SSO

StoreHeader

XmlToJson

Próximas etapas

Recursos adicionais