Tutorial: Usar a extensão de Gerenciamento de API do Azure para Visual Studio Code para importar e gerenciar APIs

APLICA-SE A: Consumo | Programador | Básico | Padrão | Prémio

Neste tutorial, você aprenderá a usar a extensão Gerenciamento de API para Visual Studio Code para operações comuns no Gerenciamento de API. Use o ambiente familiar do Visual Studio Code para importar, atualizar, testar e gerenciar APIs.

Sabe como:

• Importar uma API para o Gerenciamento de API
• Editar a API
• Aplicar políticas de gerenciamento de API
• Testar a API

Para obter uma introdução a mais recursos de Gerenciamento de API, consulte os tutoriais de Gerenciamento de API usando o portal do Azure.

Pré-requisitos

• Entenda a terminologia do Gerenciamento de API do Azure.
• Certifique-se de ter instalado o Visual Studio Code e a extensão mais recente do Azure API Management para Visual Studio Code.
• Crie uma instância de Gerenciamento de API.

Importar uma API

O exemplo a seguir importa uma especificação OpenAPI no formato JSON para o Gerenciamento de API. A Microsoft fornece a API de back-end usada neste exemplo e a hospeda no Azure em https://conferenceapi.azurewebsites.net.

1. No Visual Studio Code, selecione o ícone do Azure na Barra de atividades.
2. No painel Explorer, expanda a instância de Gerenciamento de API que você criou.
3. Clique com o botão direito do mouse em APIs e selecione Importar do OpenAPI Link.
4. Quando solicitado, insira os seguintes valores:

   1. Um link OpenAPI para conteúdo em formato JSON. Para este exemplo: https://conferenceapi.azurewebsites.net?format=json.

      Este arquivo especifica o serviço de back-end que implementa a API de exemplo, neste caso https://conferenceapi.azurewebsites.net. O Gerenciamento de API encaminha solicitações para este serviço Web.

   2. Um nome de API, como demo-conference-api, que é exclusivo na instância de Gerenciamento de API. Esse nome pode conter apenas letras, número e hífenes. O primeiro e o último caracteres devem ser alfanuméricos. Esse nome é usado no caminho para chamar a API.

Depois que a API é importada com êxito, ela aparece no painel Explorer e as operações de API disponíveis aparecem no nó Operações .

Editar a API

Você pode editar a API no Visual Studio Code. Por exemplo, edite a descrição JSON do Gerenciador de Recursos da API na janela do editor para remover o protocolo http usado para acessar a API.

Para editar o formato OpenAPI, clique com o botão direito do mouse no nome da API no painel Explorer e selecione Edit OpenAPI. Faça as alterações e selecione Salvar arquivo>.

Aplicar políticas à API

O Gerenciamento de API fornece políticas que você pode configurar para suas APIs. As políticas são uma coleção de declarações. Essas instruções são executadas sequencialmente na solicitação ou resposta de uma API. As políticas podem ser globais, que se aplicam a todas as APIs em sua instância de Gerenciamento de API, ou específicas para um produto, uma API ou uma operação de API.

Esta seção mostra como aplicar políticas de saída comuns à sua API que transformam a resposta da API. As políticas neste exemplo alteram cabeçalhos de resposta e ocultam URLs de back-end originais que aparecem no corpo da resposta.

1. No painel Explorer, selecione Policy na demo-conference-api que você importou. O arquivo de política é aberto na janela do editor. Esse arquivo configura políticas para todas as operações na API.

2. Atualize o arquivo com o seguinte conteúdo no <outbound> elemento :

   [...]
   <outbound>
       <set-header name="Custom" exists-action="override">
           <value>"My custom value"</value>
       </set-header>
       <set-header name="X-Powered-By" exists-action="delete" />
       <redirect-content-urls />
       <base />
   </outbound>
   [...]
   

   • A primeira set-header política adiciona um cabeçalho de resposta personalizado para fins de demonstração.
   • A segunda set-header política exclui o cabeçalho X-Powered-By , se existir. Esse cabeçalho pode revelar a estrutura do aplicativo usada no back-end da API, e os editores geralmente a removem.
   • A redirect-content-urls política reescreve (máscaras) links no corpo da resposta para que eles apontem para os links equivalentes por meio do gateway de Gerenciamento de API.

3. Guarde o ficheiro. Se lhe for pedido, selecione Carregar para carregar o ficheiro para a nuvem.

Testar a API

Para testar a API, obtenha uma chave de assinatura e faça uma solicitação ao gateway de Gerenciamento de API.

Obter a chave de subscrição

Você precisa de uma chave de assinatura para sua instância de Gerenciamento de API para testar a API importada e as políticas aplicadas.

1. No painel Explorer, clique com o botão direito do mouse no nome da sua instância de Gerenciamento de API.

2. Selecione Copiar chave de assinatura. Essa chave é para a assinatura interna de todos os acessos que é criada quando você cria uma instância de Gerenciamento de API.

   

   Atenção

   A assinatura de acesso total permite o acesso a todas as APIs nesta instância de Gerenciamento de API e só deve ser usada por usuários autorizados. Nunca o use para acesso rotineiro à API ou incorpore a chave de acesso total em aplicativos cliente.

Testar uma operação de API

1. No painel Explorer, expanda o nó Operações na demo-conference-api que você importou.
2. Selecione uma operação como GetSpeakers e, em seguida, clique com o botão direito do mouse na operação e selecione Operação de teste.
3. Na janela do editor, ao lado de Ocp-Apim-Subscription-Key, substitua {{SubscriptionKey}} pela chave de assinatura que você copiou.
4. Ao lado de Ocp-Apim-Trace, digite false. Essa configuração desabilita o rastreamento de solicitações.
5. Selecione Enviar pedido.

Quando a solicitação é bem-sucedida, o back-end responde com 200 OK e alguns dados.

Observe os seguintes detalhes na resposta:

• O cabeçalho Personalizado é adicionado à resposta.
• O cabeçalho X-Powered-By não aparece na resposta.
• As URLs para o back-end da API são redirecionadas para o gateway de Gerenciamento de API, neste caso https://apim-hello-world.azure-api.net/demo-conference-api.

Processamento de solicitação de rastreamento

Opcionalmente, você pode obter informações detalhadas de rastreamento de solicitações para ajudá-lo a depurar e solucionar problemas da API.

Para rastrear o processamento de solicitações, primeiro habilite a configuração Permitir rastreamento para a assinatura usada para depurar sua API. Para conhecer as etapas para habilitar essa configuração usando o portal, consulte Verificar a configuração de rastreamento de permissão. Para limitar a divulgação não intencional de informações sensíveis, o rastreamento é permitido por apenas 1 hora.

Depois de permitir o rastreamento com sua assinatura, siga estas etapas:

1. No painel Explorer, expanda o nó Operações na demo-conference-api que você importou.
2. Selecione uma operação como GetSpeakers e, em seguida, clique com o botão direito do mouse na operação e selecione Operação de teste.
3. Na janela do editor, ao lado de Ocp-Apim-Subscription-Key, substitua {{SubscriptionKey}} pela chave de assinatura que você deseja usar.
4. Ao lado de Ocp-Apim-Trace, digite true. Essa configuração permite o rastreamento para essa solicitação.
5. Selecione Enviar pedido.

Quando a solicitação é bem-sucedida, a resposta de back-end inclui um cabeçalho Ocp-APIM-Trace-Location .

Selecione o link ao lado de Ocp-APIM-Trace-Location para ver as informações de rastreamento de entrada, back-end e saída. As informações de rastreamento ajudam a determinar onde os problemas ocorrem depois que a solicitação é feita.

Gorjeta

Quando você testa operações de API, a extensão Gerenciamento de API permite depuração de política opcional (disponível somente na camada de serviço do desenvolvedor).

Clean up resources (Limpar recursos)

Quando não for mais necessário, remova a instância de Gerenciamento de API clicando com o botão direito do mouse e selecionando Abrir no Portal para excluir o serviço de Gerenciamento de API e seu grupo de recursos.

Como alternativa, você pode selecionar Excluir Gerenciamento de API para excluir apenas a instância de Gerenciamento de API (essa operação não exclui seu grupo de recursos).

Conteúdos relacionados

Este tutorial introduziu vários recursos da extensão de gerenciamento de API para Visual Studio Code. Você pode usar esses recursos para importar e gerenciar APIs. Aprendeu a:

• Importar uma API para o Gerenciamento de API
• Editar a API
• Aplicar políticas de gerenciamento de API
• Testar a API

A extensão Gerenciamento de API fornece mais recursos para trabalhar com suas APIs. Por exemplo, depurar políticas (disponíveis na camada de serviço do desenvolvedor) ou criar e gerenciar valores nomeados.