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. Para este exemplo, você importa o API do Petstore de software livre.

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://petstore.swagger.io/v2/swagger.json .

      Esse arquivo especifica o serviço de back-end que implementa a API de exemplo e as operações às quais ele dá suporte.

   2. Um nome de API, como petstore, 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, que é realçado na seguinte captura de tela:

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 comuns de entrada e saída à sua API.

1. No painel do Explorer, selecione Política na API pastore 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:

   <policies>
       <inbound>
           <rate-limit calls="3" renewal-period="15" />
           <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>
   

   • A política rate-limit na seção inbound limita o número de chamadas à API para 3 a cada 15 segundos.
   • A política set-header na seção outbound adiciona um cabeçalho de resposta personalizado para fins de demonstração.

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 API petstore importada.
2. Selecione uma operação, como [GET] Encontrar pet por ID, clique com o botão direito do mouse na operação e escolha Testar Operação.
3. Na janela do editor, substitua 5 pelo parâmetro petId na URL de solicitação.
4. Na janela do editor, ao lado de Ocp-Apim-Subscription-Key, substitua {{SubscriptionKey}} pela chave de assinatura copiada.
5. 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.

Agora, teste a política de limitação de taxa. Selecione Enviar solicitação várias vezes seguidas. Depois de enviar muitas solicitações no período configurado, você obtém a resposta 429 Too Many Requests.

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.