Todos os produtos
Search

Este produto

    API Gateway:Configure policies and plug-ins

    Central de documentação

    API Gateway:Configure policies and plug-ins

    Última atualização: Jun 27, 2026

    O Cloud-native API Gateway oferece suporte a políticas e plug-ins nos níveis de API e de operação para melhorar a segurança, o desempenho e a manutenibilidade.

    Importante

    • As alterações na configuração de políticas entram em vigor imediatamente, sem necessidade de republicar a API.

    • Por padrão, as configurações de plug-ins no nível da API também se aplicam ao nível da operação.

    • Não é possível excluir políticas de nível de API no nível da operação. No entanto, políticas de nível de operação podem substituir políticas de nível de API.

    Procedimento

    1. Adicione políticas de API de uma das duas formas a seguir:

      APIs fora de uma instância

      1. Faça login no console do Cloud-native API Gateway. No painel de navegação à esquerda, selecione APIs e escolha uma região na barra de menu superior.

      2. Clique em a API desejada e selecione a instância de destino na lista suspensa.image

      APIs dentro de uma instância

      1. Faça login no console do Cloud-native API Gateway. No painel de navegação à esquerda, selecione Instances e escolha uma região na barra de menu superior.

      2. Na página Instances, clique em o ID da instância de gateway desejada. No painel de navegação à esquerda, selecione APIs e clique em a API alvo.

    2. Configure políticas e plug-ins no nível da API ou da operação:

      • Nível da API: Clique em a aba API Policy Configuration para definir políticas e plug-ins de nível de API para todas as operações. Em seguida, clique em Enable Policy/Plug-in.

      • Nível da operação: Na aba Operations, clique em a operação desejada, selecione a aba Policy Configuration e clique em Enable Policy/Plug-in.

    3. No painel Enable Policy/Plug-in, selecione e configure uma política ou plug-in na seção Políticas ou Plug-ins.

    Políticas

    Política de limitação de taxa

    A limitação de taxa controla o volume de requisições por API e operação dentro de um limiar configurado durante um período especificado. Ela impede que requisições externas sobrecarreguem os serviços de backend e evita falhas em cascata ao rejeitar requisições excedentes sob alta concorrência.

    As políticas de limitação incluem controle de concorrência, modelagem de tráfego e circuit breaking.

    • Política de controle de concorrência: Limita o número total de requisições simultâneas processadas pelo gateway. Quando o limiar é atingido, novas requisições são rejeitadas. Defina o limiar de acordo com a capacidade do seu backend.

      Procedimento

      Na página Add Policy, clique em o cartão Concurrency Control. No painel Add Policy: Concurrency control, configure os parâmetros a seguir.

      Parâmetro

      Descrição

      Enable or Not

      Ativa a política de controle de concorrência.

      Overall Concurrency Threshold

      Defina o Overall Concurrency Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Defina o HTTP Status Code da resposta. O valor padrão é 429.

      Type of Returned Content

      Selecione um Type of Returned Content: Regular Text ou application/json.

      HTTP Text

      Insira o conteúdo do corpo da resposta.

      Return Specific Content

      Redirect URL

      Insira a Redirect URL.

    • Política de modelagem de tráfego: Monitora as consultas por segundo (QPS) de APIs e operações. Quando o QPS excede o limiar, novas requisições são rejeitadas para proteger os serviços de backend contra picos de tráfego.

      Procedimento

      Na página Add Policy, clique em o cartão Traffic Shaping. No painel Add Policy: Traffic shaping, configure os parâmetros a seguir.

      Parâmetro

      Descrição

      Enable or Not

      Ativa a política de modelagem de tráfego.

      Overall QPS Threshold

      Defina o Overall QPS Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Defina o HTTP Status Code da resposta. O valor padrão é 429.

      Type of Returned Content

      Selecione um Type of Returned Content: Regular Text ou application/json.

      HTTP Text

      Insira o conteúdo do corpo da resposta.

      Redirect to Specified Page

      Redirect URL

      Insira a Redirect URL.

    • Política de circuit breaking: Monitora o tempo de resposta ou a taxa de erros de APIs e operações. Ao atingir um limiar, o circuit breaker é acionado e falha as requisições subsequentes por um período definido, prevenindo falhas em cascata. Após o tempo limite, o gateway permite um número limitado de requisições de teste para verificar se o backend se recuperou.

      Procedimento

      Na página Add Policy, clique em o cartão Circuit Breaking. No painel Add Policy: Circuit breaking, configure os parâmetros a seguir.

      Parâmetro

      Descrição

      Enable or Not

      Ativa a política de circuit breaking.

      Statistical Window Duration

      Janela de tempo para análise estatística. Valores válidos: de 1 segundo a 120 minutos.

      Minimum Number of Requests

      Número mínimo de requisições dentro de uma janela de tempo necessário para acionar o circuit breaking. Se a contagem estiver abaixo deste valor, o circuit breaking não será acionado mesmo que o limiar seja atingido.

      Threshold Type

      Selecione Slow Call Ratio (%) ou Exception Ratio (%) como limiar.

      1. Ao selecionar Slow Call Ratio (%), defina o Slow Call RT (tempo máximo de resposta). Requisições que excederem esse valor contam como chamadas lentas. Se a proporção de chamadas lentas ultrapassar o limiar dentro de uma janela de tempo (com requisições suficientes), o circuit breaking é acionado pela duração configurada. O circuito entra então em estado semiaberto: se a próxima requisição respeitar o limite de RT, a operação normal é retomada; caso contrário, ele é acionado novamente.

      2. Ao selecionar Exception Ratio (%), defina o limiar da taxa de erros. Se a taxa de erros exceder o limiar dentro de uma janela de tempo (com requisições suficientes), o circuit breaking é acionado pela duração configurada.

      Slow Call RT

      Especifique o Slow Call RT permitido (tempo máximo de resposta) em milissegundos.

      Circuit Breaking Ratio Threshold

      Limiar de proporção de chamadas lentas ou erros. Valores válidos: de 0 a 100 (0% a 100%).

      Circuit breaking duration (s)

      Duração em que o circuito permanece aberto após ser acionado. As requisições falham rapidamente durante este período.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Defina o HTTP Status Code da resposta. O valor padrão é 429.

      Type of Returned Content

      Selecione um Type of Returned Content: Regular Text ou application/json.

      HTTP Text

      Insira o conteúdo do corpo da resposta.

      Redirect to Specified Page

      Redirect URL

      Insira a Redirect URL.

    Política de reescrita

    As políticas de reescrita modificam caminhos de requisição e cabeçalhos de host antes do encaminhamento aos serviços de backend, garantindo que as requisições cheguem aos endpoints corretos.

    Procedimento

    Na página Add Policy, clique em HTTP Rewrite. No painel Add Policy: HTTP Rewrite, configure os parâmetros.

    • Reescrita de caminho

      Para reescritas de caminho, o Cloud-native API Gateway suporta os dois modos a seguir.

      • Reescrita constante: Suportada apenas no nível da operação.

      • Regex Rewrite: Suportada tanto nos níveis de operação quanto de API.

      Reescrita constante

      A reescrita constante permite substituir o prefixo do caminho de uma requisição recebida.

      Exemplo 1

      O caminho original da requisição é /app/test, mas o caminho encaminhado ao serviço de backend deve ser /test. A configuração recomendada é:

      • Condição de correspondência da operação da API: Defina o tipo de correspondência como Prefix Match e o caminho como /app/.

      • Regra de reescrita: Defina o tipo de reescrita como Constant Rewrite e o caminho como /.

      Nota

      O caminho de correspondência da operação deve ser definido como /app/ porque a reescrita constante substitui apenas o prefixo correspondido. Se o caminho de correspondência fosse definido como /app, o caminho reescrito se tornaria //test, o que está incorreto.

      Exemplo 2

      O caminho original da requisição é /v1/test, mas o caminho encaminhado ao serviço de backend deve ser /v2/test. A configuração recomendada é:

      • Condição de correspondência da operação da API: Defina o tipo de correspondência como Prefix Match e o caminho como /v1.

      • Regra de reescrita: Defina o tipo de reescrita como Constant Rewrite e o caminho como /v2.

      Importante

      A reescrita constante exige que o tipo de correspondência da operação da API seja Prefix Match. Os tipos Exact Match e Regex Match não suportam reescrita constante. Como o Prefix Match se aplica a todas as requisições que começam com aquele prefixo, esteja ciente de que todas serão reescritas. Se precisar de um direcionamento mais específico, use Regex Rewrite.

      Reescrita regex

      A reescrita regex modifica partes do caminho original da requisição usando um padrão de expressão regular e uma string de substituição. O padrão segue a Sintaxe de Expressão Regular.

      Exemplo 1

      O caminho original da requisição é /aaa/one/bbb/one/ccc, mas o caminho encaminhado ao serviço de backend deve ser /aaa/two/bbb/two/ccc. A configuração recomendada é:

      • Condição de correspondência da operação da API: Defina o tipo de correspondência como Exact Match e o caminho como /aaa/one/bbb/one/ccc.

      • Regra de reescrita: Defina o tipo de reescrita como Regex Rewrite, o padrão como one e a string de substituição como two.

      Exemplo 2

      O caminho original da requisição corresponde a /httpbin/(.*)/(.*). Você deseja remover o prefixo /httpbin e trocar as posições dos dois grupos capturados. A configuração recomendada é:

      • Condição de correspondência da operação da API: Defina o tipo de correspondência como Regex Match e o caminho como /httpbin/(.*)/(.*).

      • Regra de reescrita: Defina o tipo de reescrita como Regex Rewrite, o padrão como /httpbin/(.*)/(.*) e a string de substituição como /\2/\1. Aqui, \1 representa o primeiro grupo capturado e \2 representa o segundo, semelhante à sintaxe $1 e $2 no Nginx.

      Exemplo 3

      Para uma API REST versionada que inclui a versão no caminho, você deseja remover o segmento de versão antes de encaminhar a requisição ao backend. Por exemplo, um caminho original /basePath/version/order/get deve ser reescrito para /basePath/order/get. A configuração recomendada é:

      • Aplique a política no nível da API usando API Policy Configuration.

      • Regra de reescrita: Defina o tipo de reescrita como Regex Rewrite, o padrão como (/.*)/version(/.*) e a string de substituição como \1\2. Aqui, \1 representa o primeiro grupo capturado e \2 representa o segundo.

      Nota

      A reescrita regex é um recurso avançado. Use Constant Rewrite sempre que possível.

    • Reescrita de cabeçalho Host

      Para reescritas de cabeçalho host, o Cloud-native API Gateway suporta reescrita constante.

      Por exemplo, se o cabeçalho Host da requisição original for test.com, mas o serviço de backend esperar dev.com, defina o host de reescrita como dev.com na política de reescrita.

    Política de modificação de cabeçalho

    A modificação de cabeçalho permite alterar cabeçalhos de requisição antes do encaminhamento ao backend, ou cabeçalhos de resposta antes do retorno ao cliente.

    Procedimento

    Na página Add Policy, clique em o cartão Edit Header. No painel Add Policy: Header Modification, configure os parâmetros a seguir.

    Parâmetro

    Descrição

    Enable

    Ativa ou desativa a política de modificação de cabeçalho.

    • Ativado: O gateway modificará os cabeçalhos de requisição e resposta conforme configurado.

    • Desativado: O gateway não modificará os cabeçalhos de requisição ou resposta.

    Header Type

    Selecione o tipo de cabeçalho a ser modificado.

    • Request: Modifica os cabeçalhos da requisição recebida.

    • Response: Modifica os cabeçalhos da resposta enviada.

    Operation Type

    Selecione a ação a ser executada.

    • Add: Adiciona um novo cabeçalho à requisição ou resposta.

      Nota

      Se já existir um cabeçalho com o mesmo nome, o novo valor será anexado ao valor existente, separado por vírgula (,).

    • Modify: Define o valor de um cabeçalho especificado na requisição ou resposta.

      Nota

      • Se o cabeçalho especificado não existir, ele será adicionado.

      • Se o cabeçalho especificado já existir, seu valor será sobrescrito.

    • Delete: Remove um cabeçalho especificado da requisição ou resposta.

    Header key

    Insira o nome do cabeçalho.

    Header value

    Insira o valor do cabeçalho.

    Política CORS

    O Cross-Origin Resource Sharing (CORS) controla o acesso a recursos de origens diferentes (domínio, esquema ou porta). Configure políticas CORS nos níveis de API e operação para especificar as origens e métodos de requisição permitidos.

    Importante

    A política CORS não se aplica a serviços mock. É necessário configurar um serviço de backend real para testes.

    Procedimento

    Na página Add Policy, clique em o cartão CORS. No painel Add Policy: CORS, configure os parâmetros a seguir.

    Parâmetro

    Descrição

    Enable

    Ative o interruptor Enable à direita.

    • Ativado: Permite requisições cross-origin das origens de terceiros configuradas.

    • Desativado: Rejeita todas as requisições cross-origin de qualquer origem de terceiros.

    Allowed Origins

    Origens com permissão para acessar recursos através de um navegador.

    • Permitir todas as origens de acesso: *.

    • Permite acesso de origens de um domínio raiz especificado: *.example.com.

    • Para permitir múltiplas origens específicas: Inicie cada origem com http:// ou https:// e separe-as com quebras de linha.

    Nota

    Este parâmetro define o cabeçalho de resposta Access-Control-Allow-Origin. Se o cabeçalho Origin de uma requisição recebida corresponder a um valor nesta lista, o cabeçalho Access-Control-Allow-Origin da resposta será definido com o valor do cabeçalho Origin da requisição.

    Allowed Methods

    Selecione os métodos HTTP permitidos para requisições cross-origin. Métodos comuns incluem GET, POST, PUT, DELETE, HEAD, OPTIONS e PATCH.

    Nota

    Este parâmetro aplica-se ao cabeçalho Access-Control-Allow-Methods.

    Trusted Request Headers

    Cabeçalhos de requisição permitidos durante requisições cross-origin, além dos cabeçalhos padrão suportados pelo navegador.

    • Permitir todos os cabeçalhos de requisição: *.

    • Para permitir múltiplos cabeçalhos específicos, insira cada nome de cabeçalho em uma nova linha.

    Nota

    Este parâmetro aplica-se ao cabeçalho Access-Control-Allow-Headers.

    Trusted Response Headers

    Cabeçalhos de resposta acessíveis aos clientes do navegador.

    • Permitir todos os cabeçalhos de resposta: *.

    • Para expor múltiplos cabeçalhos específicos, insira cada nome de cabeçalho em uma nova linha.

    Nota

    Este parâmetro afeta o cabeçalho Access-Control-Expose-Headers.

    Allow to Carry Credentials

    Define se o navegador envia credenciais (cookies, cabeçalhos de autorização) com requisições cross-origin.

    Nota

    Este parâmetro aplica-se ao cabeçalho Access-Control-Allow-Credentials.

    Precheck Expiration Time

    Tempo durante o qual o navegador armazena em cache a resposta preflight (OPTIONS) para requisições não simples.

    Nota

    Este parâmetro aplica-se ao cabeçalho Access-Control-Max-Age.

    Política de replicação de tráfego

    A replicação de tráfego espelha uma porcentagem do tráfego em produção para um serviço especificado, destinada a testes de simulação e diagnóstico de falhas.

    Procedimento

    Na página Add Policy, clique em o cartão Mirror Traffic. No painel Add Policy: Traffic Replication, configure os parâmetros a seguir.

    Parâmetro

    Descrição

    Enable

    Ativa ou desativa a política de replicação de tráfego para a API ou operação.

    Destination Service

    Serviço para o qual o tráfego replicado é encaminhado.

    Nota

    O serviço de destino deve usar o protocolo HTTP ou HTTPS.

    Port

    Porta do serviço de destino. Também é possível selecionar uma porta dinâmica.

    Nota

    Portas dinâmicas são adequadas para serviços cujas portas mudam dinamicamente. Esta opção não é suportada para serviços multiporta.

    Traffic Mirror Percentage

    Porcentagem de tráfego a ser replicada. Valores válidos: de 0 a 100.

    Nota

    Se você definir este parâmetro como 50, 50% do tráfego da API ou operação atual será replicado para o serviço de destino.

    Política de timeout

    Configure o tempo máximo que o gateway aguarda por uma resposta do backend. Se nenhuma resposta for recebida dentro desse tempo, o gateway retorna um erro HTTP 504 (Gateway Timeout).

    Procedimento

    Na página Add Policy, clique em o cartão Timeout. No painel Add Policy: Timeout, configure os parâmetros a seguir.

    Nota

    Após configurar e ativar a política de timeout, verifique se o comportamento de timeout do serviço atende aos seus requisitos de negócio.

    Parâmetro

    Descrição

    Enable

    Especifique se a política de timeout deve ser ativada.

    • Ativado: A política de timeout para a API ou operação entra em vigor.

    • Desativado: A política de timeout para a API ou operação é desativada.

    Timeout Period

    Defina a duração do timeout para a API ou operação, em segundos.

    Nota

    Se definido como 0 ou se a política estiver desativada, o gateway aguardará indefinidamente por uma resposta.

    Política de nova tentativa

    Configure novas tentativas automáticas para requisições com falha. As condições de nova tentativa incluem falha de conexão, indisponibilidade do backend e códigos de status HTTP específicos.

    Condições de nova tentativa

    Quando um serviço de backend retorna um erro 5xx, o Cloud-native API Gateway tenta automaticamente a requisição com falha novamente, de acordo com o número de tentativas configurado.

    image

    • As condições de nova tentativa para o protocolo HTTP são as seguintes:

      • 5xx: O gateway tenta a requisição novamente se o serviço de backend retornar qualquer resposta 5xx, ou se uma conexão for desconectada, redefinida ou expirar.

        Nota

        5xx inclui as condições connect-failure e refused-stream.

      • reset: O gateway tenta a requisição novamente se a conexão for desconectada, redefinida ou expirar.

      • connect-failure: O gateway tenta a requisição novamente se ela falhar devido a uma falha de conexão.

      • refused-stream: O gateway tenta a requisição novamente se o serviço de backend redefinir o stream com um código de erro REFUSED_STREAM.

      • retriable-status-codes: O gateway tenta a requisição novamente se o código de status HTTP da resposta corresponder a um dos códigos de status especificados pelo usuário.

        Nota

        Os códigos de status de nova tentativa só podem ser usados se retriable-status-codes for especificado na condição de nova tentativa.

    • As condições de nova tentativa para o protocolo gRPC são as seguintes:

      • cancelled: Tenta novamente quando o serviço gRPC de backend retorna cancelled.

      • deadline-exceeded: Tenta novamente quando o serviço gRPC de backend retorna deadline-exceeded.

      • internal: Tenta novamente quando o serviço gRPC de backend retorna internal.

      • resource-exhausted: Tenta novamente quando o serviço gRPC de backend retorna resource-exhausted.

      • unavailable: Tenta novamente quando o serviço gRPC de backend retorna unavailable.

    Procedimento

    Na página Add Policy, clique em o cartão Retry. No painel Add Policy: Retry, configure os parâmetros a seguir.

    Nota

    Após configurar e ativar a política de nova tentativa, verifique se o comportamento de nova tentativa do serviço atende aos seus requisitos de negócio.

    Parâmetro

    Descrição

    Enable

    Especifique se a política de nova tentativa deve ser ativada.

    • Ativado: A política de nova tentativa para a API ou operação entra em vigor.

    • Desativado: A política de nova tentativa para a API ou operação é desativada.

      Mesmo se você desativar as novas tentativas, o gateway possui uma configuração interna padrão de nova tentativa. O número de tentativas tem como padrão 2, e as condições de nova tentativa têm como padrão connect-failure, refused-stream, unavailable, cancelled e retriable-status-codes.

    Retry Times

    Número máximo de tentativas. Valores válidos: de 0 a 10. Recomendado: 2 ou menos.

    Um valor de 0 desativa as novas tentativas.

    Retry Condition

    Condições que acionam uma nova tentativa.

    Retry Status Code

    Códigos de status HTTP que acionam uma nova tentativa. Múltiplos códigos podem ser configurados.

    Importante

    Você deve definir Retry Condition como retriable-status-codes para configurar o Retry Status Code.

    Plug-ins

    1. Clique em a aba Add Plug-in.

    2. Na seção Quick Navigation, localize o plug-in desejado por tipo ou nome e clique em seu cartão.

      • Se o plug-in ainda não estiver instalado, clique em Install and Configure na caixa de diálogo. Configure as regras e ative-o.

      • Se o plug-in já estiver instalado, configure suas regras e ative-o na caixa de diálogo.

    3. Clique em OK. Você retornará à lista de plug-ins da API, onde poderá visualizar o status do novo plug-in.

      image