Tutorial: Transformar e proteger sua API

APLICA-SE A: todas as camadas do Gerenciamento de API

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

Dica

As equipes de API podem usar esse recurso nos workspaces. Os workspaces fornecem acesso administrativo isolado às APIs e aos respectivos ambientes de runtime de API.

Por exemplo, talvez você queira definir um cabeçalho de resposta personalizado. Ou proteger sua API de back-end configurando uma política de limite de taxa para que a API não seja superutilizada 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.

Observação

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

Neste tutorial, você aprenderá a:

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

Pré-requisitos

• Conheça a terminologia do Gerenciamento de API do Azure.
• Compreenda o conceito de políticas no Gerenciamento de API do Azure.
• Conclua o início rápido a seguir: Criar uma instância do Gerenciamento de API do Azure. Para este tutorial, recomendamos que você use uma das camadas clássicas ou v2, por exemplo, a camada Desenvolvedor ou a camada Básica v2. A camada Consumo não dá suporte a todas as políticas usadas neste tutorial.
• Além disso, conclua o seguinte tutorial: Importar e publicar sua primeira API.

Navegar até a instância de Gerenciamento de API

1. No portal do Azure, pesquise e selecione Serviços de Gerenciamento de API:

   

2. Na página Serviços do Gerenciamento de API, selecione sua instância do Gerenciamento de API:

   

Testar a resposta original

Para ver a resposta original:

1. Em sua instância de serviço do Gerenciamento de API, selecione APIs.
2. Selecione Swagger Petstore na lista de APIs.
3. Selecione a guia Testar na parte superior da tela.
4. Selecione a operação GET Finds pets by status e, opcionalmente, selecione um valor diferente do statusParâmetro de consulta. Selecione Enviar.

A resposta original da API deve se parecer com a 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 conteúdos 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 política set-header. Aqui você usa um editor de política baseado em formulário que simplifica a configuração da política.

1. Selecione Swagger Petstore>Design>Todas as operações.

2. Na seção Processamento de saída, selecione + Adicionar política.

   

3. Na janela Adicionar política de saída, selecione Definir cabeçalhos.

   

4. Para configurar a política de Definir cabeçalhos, faça o seguinte:

   1. Em Nome, insira Personalizado.
   2. Em Valor, selecione + Adicionar valor. Insira "Meu valor personalizado".
   3. Selecione Salvar.

5. Após a configuração, um elemento de política set-header aparece na seção Processamento de saída.

   

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

Esta seção mostra como adicionar proteção à API de back-end configurando limites de taxa para que a API não seja excessivamente utilizada pelos desenvolvedores. Este exemplo mostra como configurar a política rate-limit-by-key usando o editor de código. Neste exemplo, o limite é definido como três chamadas por 15 segundos. Depois de 15 segundos, um desenvolvedor pode repetir a chamada à API.

Observação

Essa política não tem suporte na camada Consumo.

1. Selecione Swagger Petstore>Design>Todas as operações.

2. Na seção Processamento de entrada, selecione o ícone do editor de código (<\>).

   

3. Posicione o cursor dentro do elemento <inbound> em uma linha em branco. Em seguida, selecione Mostrar snippets no canto superior direito da tela.

   

4. Na janela à direita, em Políticas de restrição de acesso, clique em Limitar taxa de chamada por chave.

   O elemento <rate-limit-by-key /> é adicionado ao cursor.

   

5. Modifique o código <rate-limit-by-key /> no elemento <inbound> para o seguinte código. Em seguida, selecione Salvar.

   <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
   

Testar as transformações

Nesse ponto, se você examinar o código no editor de códigos, suas políticas serão semelhantes ao código a seguir:

<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 restante desta seção testa as transformações de política que você definir neste artigo.

Testar o cabeçalho de resposta personalizado

1. Selecione Swagger Petstore>Teste.

2. Selecione a operação GET Finds pets by status e, opcionalmente, selecione um valor diferente do statusParâmetro de consulta. Selecione Enviar.

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

   

Testar o limite de taxa (limitação)

1. Selecione Swagger Petstore>Teste.

2. Selecione a operação GET Finds Pets by 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.

   

3. Aguarde 15 segundos ou mais e selecione Enviar novamente. Neste momento, você deve obter uma resposta 200 OK.

Obter 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. Você 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ítica.
• O GitHub Copilot para Azure no Visual Studio Code fornece assistência de criação de política 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 de política. Você pode solicitar o Copilot Chat ou o Copilot Edits com linguagem natural para criar e refinar definições de políticas existentes.

Exemplo de solicitação:

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

Copilot é alimentado pela IA, portanto, surpresas e erros são possíveis. Para obter mais informações, consulte perguntas frequentessobre uso geral do Copilot.

Resumo

Neste tutorial, você aprendeu a:

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

Próximas etapas

Prosseguir para o próximo tutorial:

Monitorar sua API