Criar, entender e depurar políticas de Gerenciamento de API do Azure no Visual Studio Code

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

Este artigo explica como usar a Extensão de Gerenciamento de API do Azure para Visual Studio Code para criar, entender e depurar políticas de Gerenciamento de API do Azure com a assistência de IA do GitHub Copilot for Azure.

As políticas de Gerenciamento de API do Azure são uma sequência de instruções que abordam preocupações transversais, como autenticação, autorização, limitação, cache e transformação, aplicadas a solicitações ou respostas de API.

Pré-requisitos

• Visual Studio Code e a versão mais recente da Extensão de Gerenciamento de API do Azure para Visual Studio Code.

• As seguintes extensões são necessárias para os cenários especificados:

  • Extensão GitHub Copilot for Azure - para criar e explicar políticas
  • Extensão do cliente REST - para depuração de políticas

• Uma instância de gerenciamento de API. Se você precisar criar um, consulte este guia de início rápido.

• Importe uma API para sua instância de Gerenciamento de API. Para obter etapas de exemplo, consulte Tutorial: Usar a extensão de gerenciamento de API para Visual Studio Code para importar e gerenciar APIs.

Restrições e limitações

• Atualmente, a depuração de políticas é suportada apenas na camada do Desenvolvedor de Gerenciamento de API.

• A depuração de políticas usa a assinatura interna de acesso total (nível de serviço) (nome para exibição "Assinatura interna de acesso total"). Tem de ser proprietário de um serviço para utilizar esta subscrição.

Criar uma política usando o GitHub Copilot para Azure

A extensão Gerenciamento de API do Azure integra-se ao GitHub Copilot para Azure para ajudá-lo a criar um rascunho de uma política. Com a assistência de IA, crie e edite políticas de forma amigável.

Para criar uma política:

1. Abra a extensão Gerenciamento de API no Visual Studio Code.

2. Selecione a instância de Gerenciamento de API com a qual deseja trabalhar.

3. Selecione o escopo da política com o qual você deseja trabalhar.

   • Para criar uma política que se aplique a todas as APIs na instância, selecione Política Global.
   • Para criar uma política que se aplique a uma API específica, em APIs, selecione a API e, em seguida, selecione Política.
   • Para criar uma política que se aplique a uma operação de API específica, selecione a operação e, em seguida, selecione Política.

4. Abra o bate-papo.

5. Na janela Chat, insira um prompt em linguagem natural para criar uma política. Examples:

   @azure I want to limit requests to 100 calls per minute
   

   @azure Create a policy that sets the backend URL to https://mybackend.contoso.com and adds a custom header to the request
   

6. O Copilot gera um rascunho de política na janela de bate-papo. Você pode refinar o prompt se quiser que o Copilot altere a saída.

7. Quando estiver pronto, selecione o botão Copiar para copiar a política para a área de transferência ou selecione Aplicar no Editor para inserir a política na janela do editor. Se estiver satisfeito com a alteração no XML da política, selecione Manter.

Explicar uma política usando o GitHub Copilot para Azure

O Copilot pode ajudar a explicar uma política existente em sua instância de Gerenciamento de API.

Para receber uma explicação:

1. Abra a extensão Gerenciamento de API no Visual Studio Code.

2. Selecione a instância de Gerenciamento de API com a qual deseja trabalhar.

3. Selecione o escopo da política com o qual você deseja trabalhar.

   • Para explicar uma política que se aplica a todas as APIs na instância, selecione Política Global.
   • Para explicar uma política que se aplica a uma API específica, em APIs, selecione a API e, em seguida, selecione Política.
   • Para explicar uma política que se aplica a uma operação de API específica, selecione a operação e, em seguida, selecione Política.

4. Na janela do editor de políticas exibida, clique com o botão direito do mouse e selecione Explicar.

5. Uma visão geral e uma explicação das políticas no documento XML da política são geradas na janela Chat.

Políticas de depuração usando a extensão VS Code

A extensão de Gerenciamento de API do Azure para Visual Studio Code fornece uma experiência de depuração que permite percorrer o pipeline de políticas ou definir um ponto de paragem ao enviar uma solicitação para o gateway.

Iniciar uma sessão de depuração

1. Abra a extensão Gerenciamento de API no Visual Studio Code.
2. Selecione a instância de Gestão de API a ser analisada.
3. Selecione a API e a operação para depurar.
4. Clique com o botão direito do mouse na operação e selecione Iniciar depuração de política.

Neste ponto, a extensão começa a estabelecer uma sessão de depuração com o gateway de Gerenciamento de API. Verifique o progresso na janela Debug Console .

Enviar um pedido de teste

Quando a sessão de depuração é estabelecida, a extensão do cliente REST abre um novo editor que permite criar e enviar uma solicitação HTTP de teste para o gateway.

O cabeçalho Ocp-Apim-Debug é adicionado automaticamente à solicitação. Este cabeçalho é necessário e o valor deve ser definido como a chave de subscrição de acesso total a nível de serviço para acionar a funcionalidade de depuração no gateway de Gestão de API.

Modifique a solicitação HTTP no editor de acordo com seu cenário de teste. Em seguida, clique em Enviar solicitação para enviar a solicitação de teste para o gateway de gerenciamento de API.

Políticas de depuração

Depois que a solicitação HTTP de teste é enviada, a extensão abre a janela de depuração, que mostra as políticas efetivas dessa operação e para na primeira política efetiva.

Para seguir o pipeline de políticas, você pode passar uma única etapa por políticas individuais ou definir um ponto de interrupção em uma política e ir diretamente para essa política.

• No painel Variáveis , inspecione os valores das variáveis criadas pelo sistema e pelo usuário.
• No painel Pontos de interrupção , exiba a lista de todos os pontos de interrupção que foram definidos.
• No painel Pilha de chamadas, visualize o escopo da política efetiva atual.

Se houver um erro durante a execução da política, você verá os detalhes do erro na política onde ele aconteceu.

Saia da sessão de depuração clicando no botão Parar quando terminar.

Conteúdo relacionado

• Saiba mais sobre a extensão de Gerenciamento de API para Visual Studio Code.
• Relatar problemas no repositório GitHub