Tutorial: Transforme e proteja sua API

2025-06-01

APLICA-SE A: Todas as camadas de gerenciamento de API

Neste tutorial, você aprenderá a configurar políticas para proteger ou transformar sua API. As políticas são uma coleção de instruções que são executadas sequencialmente na solicitação ou resposta de uma API que modifica o comportamento da API.

Gorjeta

As equipes de API podem usar esse recurso em espaços de trabalho. Os espaços de trabalho fornecem acesso administrativo isolado a APIs e ambientes de execução próprios para APIs.

Por exemplo, talvez você queira definir um cabeçalho de resposta personalizado. Ou proteja sua API de back-end configurando uma política de limite de taxa, para que a API não seja usada em excesso pelos desenvolvedores. Esses exemplos são uma introdução simples às políticas de gerenciamento de API. Para obter mais opções de política, consulte Políticas de gerenciamento de API.

Nota

Por padrão, o Gerenciamento de API configura uma política global forward-request . A forward-request política é necessária para que o gateway conclua uma solicitação para um serviço de back-end.

Neste tutorial, irá aprender a:

Transformar uma API para definir um cabeçalho de resposta personalizado
Proteger uma API adicionando uma política de limite de taxa (restrição)
Testar as transformações

Pré-requisitos

Conhecer a terminologia da Gestão de API do Azure.
Compreender o conceito das políticas da Gestão de API do Azure.
Conclua o seguinte guia de início rápido: Criar uma instância da Gestão de API do Azure. Para este tutorial, recomendamos que você use uma das camadas clássica ou v2, por exemplo, a camada Desenvolvedor ou a camada Básica v2. A camada Consumo não suporta todas as políticas usadas neste tutorial.
Conclua também o tutorial seguinte: Importar e publicar a sua primeira API.

Vá para a sua instância de Gestão de API

No Portal do Azure , procure e selecione Serviços de Gestão de API:
Na página de serviços de Gerenciamento de API, selecione sua instância de Gerenciamento de API:

Testar a resposta original

Para ver a resposta original:

Na instância do serviço Gerenciamento de API, selecione APIs.
Selecione Swagger Petstore na sua lista de APIs.
Selecione o separador Teste, na parte superior do ecrã.
Selecione a operação GET Localiza animais de estimação por status e, opcionalmente, selecione um valor diferente do parâmetro de consulta de status. Selecione Enviar.

A resposta original da API deve ser semelhante à seguinte resposta:

Transformar uma API para adicionar um cabeçalho de resposta personalizado

O Gerenciamento de API inclui várias políticas de transformação que você pode usar para modificar cargas úteis de solicitação ou resposta, cabeçalhos ou códigos de status. Neste exemplo, você define um cabeçalho de resposta personalizado na resposta da API.

Definir a política de transformação

Esta seção mostra como configurar um cabeçalho de resposta personalizado usando a set-header política. Aqui você usa um editor de política baseado em formulário que simplifica a configuração da política.

Selecione Swagger Petstore>Design>Todas as operações.
Na seção Processamento de Saída, selecione + Adicionar regra.
Na janela Adicionar política de saída, selecione Definir cabeçalhos.
Para configurar a política Definir cabeçalhos, faça o seguinte:
1. Em Nome, insira Personalizado.
2. Em Valor, selecione + Adicionar valor. Digite "Meu valor personalizado".
3. Selecione Guardar.
Após a configuração, um elemento de política set-header aparece na secção de Processamento de saída.

Proteger uma API adicionando uma política de limitação de taxa (estrangulamento)

Esta seção mostra como adicionar proteção à sua API de back-end configurando limites de taxa, para que a API não seja usada em excesso pelos desenvolvedores. Este exemplo mostra como configurar a rate-limit-by-key política usando o editor de códigos. Neste exemplo, o limite é definido como três chamadas a cada 15 segundos. Após os 15 segundos, um programador pode tentar chamar a API novamente.

Nota

Esta política não é suportada na camada Consumo.

Selecione Swagger Petstore>Design>Todas as operações.
Na seção de Processamento de entrada, selecione o ícone do editor de código ().
Posicione o cursor dentro do <inbound> elemento em uma linha em branco. Em seguida, selecione Mostrar trechos no canto superior direito da tela.
Na janela direita, em Políticas de restrição de acesso, selecione Limitar taxa de chamadas por chave.

O <rate-limit-by-key /> elemento é adicionado no cursor.
Modifique o seu <rate-limit-by-key /> código no elemento <inbound> para o código a seguir. Em seguida, selecione Guardar.
```
<rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
```

Testar as transformações

Neste ponto, se você examinar o código no editor de códigos, suas políticas se parecerão com o seguinte código:

<policies>
     <inbound>
         <rate-limit calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
         <base />
     </inbound>
     <outbound>
         <set-header name="Custom" exists-action="override">
             <value>"My custom value"</value>
           </set-header>
         <base />
     </outbound>
     <on-error>
         <base />
     </on-error>
 </policies>

O resto desta secção testa as transformações de política que definiu neste artigo.

Testar o cabeçalho de resposta personalizado

Selecione Swagger Petstore>Test.
Selecione a operação GET Localiza animais de estimação por status e, opcionalmente, selecione um valor diferente do parâmetro de consulta de status. Selecione Enviar.

Como você pode ver, o cabeçalho de resposta personalizado é adicionado:

Testar o limite de taxa (restrição)

Selecione Swagger Petstore>Test.
Selecione a operação GET Localiza animais de estimação por status . Selecione Enviar várias vezes seguidas.

Depois de enviar muitas solicitações no período configurado, você obtém a resposta 429 Solicitações Demais .
Aguarde 15 segundos ou mais e selecione Enviar novamente. Neste momento, deve obter uma resposta 200 OK.

Obtenha a assistência do Copilot

Você pode obter assistência de IA do Copilot para criar e editar suas definições de política de Gerenciamento de API. Você pode usar o Copilot para criar e atualizar políticas que correspondam aos seus requisitos específicos sem precisar conhecer a sintaxe XML. Também pode obter explicações sobre as políticas existentes. E o Copilot pode ajudá-lo a traduzir políticas que você pode ter configurado em outras soluções de gerenciamento de API.

O Microsoft Copilot no Azure fornece assistência de criação de políticas com prompts de linguagem natural no portal do Azure. Você pode criar políticas no editor de políticas de Gerenciamento de API e pedir ao Copilot para explicar as seções de políticas.
O GitHub Copilot para Azure no Visual Studio Code fornece assistência de criação de políticas no Visual Studio Code e você pode usar a Extensão de Gerenciamento de API do Azure para Visual Studio Code para acelerar a configuração da política. Você pode solicitar o Copilot Chat ou o Copilot Edits com linguagem natural para criar e refinar as definições de política em vigor.

Exemplo de prompt:

Generate a policy that adds an Authorization header to the request with a Bearer token.

O copiloto é alimentado por IA, por isso surpresas e erros são possíveis. Para obter mais informações, consulte Perguntas frequentes sobre o uso geral do Copilot.

Resumo

Neste tutorial, ficou a saber como:

Transformar uma API para definir um cabeçalho de resposta personalizado
Proteger uma API adicionando uma política de limite de taxa (restrição)
Testar as transformações

Próximos passos

Avance para o tutorial seguinte:

Monitorizar a sua API

Partilhar via