Tutorial: Como usar a extensão de Gerenciamento de API para Visual Studio Code para importar e gerenciar APIs

APLICA-SE A: Consumo | Desenvolvedor | Básico | Standard | Premium

Nesse tutorial, você aprenderá a usar a Extensão de Gerenciamento de API para Visual Studio Code para executar operações comuns no Gerenciamento de API. Use o ambiente do Visual Studio Code que você já conhece para importar, atualizar, testar e gerenciar APIs.

Você aprenderá 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 do Gerenciamento de API, confira os tutoriais do Gerenciamento de API usando o portal do Azure.

Pré-requisitos

• Noções básicas sobre a terminologia do Gerenciamento de API do Azure.
• Verifique se você instalou o Visual Studio Code e a última Extensão do Gerenciamento de API do Azure 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 do Explorer, expanda a instância do Gerenciamento de API que você criou.
3. Clique com o botão direito do mouse em APIs e selecione Importar do Link de OpenAPI.
4. Quando precisar, insira os seguintes valores:

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

      Esse arquivo especifica o serviço de back-end que implementa a API de exemplo, nesse caso https://conferenceapi.azurewebsites.net. O Gerenciamento de API envia as solicitações para esse endereço.

   2. Um nome de API, como demo-conference-api, que seja exclusivo na instância do Gerenciamento de API. Esse nome só pode conter letras, números e hifens. O primeiro e o último caracteres precisam ser alfanuméricos. Esse nome é usado no caminho para chamar a API.

Depois que a API for importada com êxito, ela será exibida no painel do Explorer e as operações de API disponíveis serão mostradas no nó Operações.

Editar a API

Edite a API no Visual Studio Code. Por exemplo, edite a descrição em JSON do Resource Manager 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 do Explorer e selecione Editar OpenAPI. Faça as alterações e selecione Arquivo>Salvar.

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 instruçõ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 na sua instância do Gerenciamento de API, ou específicas a um produto, uma API ou uma operação de API.

Esta seção mostra como aplicar políticas de saída comuns à API que transforma a resposta da API. As políticas deste exemplo alteram os cabeçalhos de resposta e ocultam as URLs de back-end originais exibidas no corpo da resposta.

1. No painel do Explorer, selecione Política na demo-conference-api importada. O arquivo de política será 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 elemento <outbound>:

   [...]
   <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 política set-header adiciona um cabeçalho de resposta personalizado para fins de demonstração.
   • A segunda política set-header exclui o cabeçalho X-Powered-By, caso ele exista. Esse cabeçalho pode revelar a estrutura do aplicativo usada no back-end da API, e os editores geralmente o removem.
   • A política redirect-content-urls reescreve (mascara) os links no corpo da resposta de modo que eles apontem para os links equivalentes por meio do gateway do Gerenciamento de API.

3. Salve o arquivo. Se solicitado, escolha Carregar para carregar o arquivo na nuvem.

Testar a API

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

Obter a chave de assinatura

Para testar a API importada que você importou e as políticas aplicadas, você precisará obter uma chave de assinatura para a instância do Gerenciamento de API.

1. No painel do Explorer, clique com o botão direito do mouse no nome da instância do 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.

   

   Cuidado

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

Testar uma operação de API

1. No painel do Explorer, expanda o nó Operações na demo-conference-api importada.
2. Selecione uma operação, como GetSpeakers, clique com o botão direito do mouse na operação e escolha Testar Operação.
3. Na janela do editor, ao lado de Ocp-Apim-Subscription-Key, substitua {{SubscriptionKey}} pela chave de assinatura copiada.
4. Selecione Enviar solicitação.

Quando a solicitação for realizada com sucesso, o back-end responderá com 200 OK e alguns dados.

Observe os seguintes detalhes na resposta:

• O cabeçalho Custom é adicionado à resposta.
• O cabeçalho X-Powered-By não é exibido na resposta.
• As URLs para o back-end de API são redirecionadas para o gateway do 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ção para ajudá-lo a depurar e solucionar problemas da API.

Para ver as etapas necessárias para habilitar o rastreamento de uma API, confira Habilitar o rastreamento para uma API. Para limitar a divulgação não intencional de informações confidenciais, por padrão, o rastreamento é permitido por apenas uma hora.

Limpar os 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 o grupo de recursos dele.

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

Conteúdo relacionado

Esse tutorial introduziu vários recursos da extensão de Gerenciamento de API para o Visual Studio Code. Você pode usar esses recursos para importar e gerenciar APIs. Você 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 de Gerenciamento de API fornece recursos adicionais para trabalhar com suas APIs. Por exemplo, depurar políticas (disponível na camada de serviço do Desenvolvedor) ou criar e gerenciar valores nomeados.