Tutorial: Importar e publicar a primeira API

APLICA-SE A: Todos os níveis de API Management

Este tutorial mostra como importar uma API backend de especificação OpenAPI em formato JSON para Azure API Management. Neste exemplo, importa a API open source Petstore.

Quando importa a API de backend para a API Management, a sua API Management torna-se a porta de entrada para a API de backend. Pode personalizar o gateway às suas necessidades no API Management sem alterar a API do backend. Para obter mais informações, veja Transformar e proteger a sua API.

Neste tutorial, irá aprender a:

Depois da importação, pode gerir a API no Azure portal.

Pré-requisitos

• Compreender a terminologia Azure API Management.
• Crie uma instância Azure API Management.

Vai à tua instância de API Management

1. No portal do Azure, pesquise e selecione serviços de Gestão de APIs:

   

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

   

Importar e publicar uma API de back-end

Esta secção mostra como importar e publicar uma API de back-end de especificação de OpenAPI.

1. Na sua instância de Gestão de API, no menu lateral em APIs, selecione APIs.

2. Selecione o tile OpenAPI.

3. Na janela Criar a partir da especificação OpenAPI, selecione Completo.

4. Insira os valores da tabela a seguir.

   Você pode definir valores de API durante a criação ou posteriormente acessando a guia Configurações .

   

   Configuração	valor	Descrição
   Especificação de OpenAPI	https://petstore3.swagger.io/api/v3/openapi.json -ou- https://petstore.swagger.io/v2/swagger.json	Especifica o serviço de back-end que implementa a API e as operações suportadas pela API. A URL do serviço de back-end aparece posteriormente como a URL do serviço Web na página de Configurações da API. Após a importação, você pode adicionar, editar, renomear ou excluir operações na especificação.
   Incluir parâmetros de consulta em modelos de operação	Selecionado (padrão)	Especifica se deve importar os parâmetros de consulta necessários na especificação como parâmetros template no API Management.
   Nome de exibição	Depois de introduzir o URL da especificação OpenAPI, a API Management preenche este campo com base no JSON.	O nome exibido no portal do desenvolvedor.
   Nome	Depois de introduzir o URL da especificação OpenAPI, a API Management preenche este campo com base no JSON.	Um nome exclusivo para a API.
   Descrição	Depois de introduzir o URL da especificação OpenAPI, a API Management preenche este campo com base no JSON.	Uma descrição opcional da API.
   Esquema do URL	HTTPS	Quais os protocolos que podem acessar à API.
   Sufixo do URL da API	loja de animais de estimação	O sufixo foi adicionado à URL base do serviço API Management. O API Management distingue e encaminha APIs pelo seu sufixo, pelo que o sufixo deve ser único para cada API de um dado publisher. Saiba mais sobre como API Management encaminha pedidos.
   Etiquetas		Tags para organizar APIs para pesquisa, agrupamento ou filtragem.
   Produtos	Ilimitado	Associação de uma ou mais APIs. Em certas camadas, a instância do API Management vem com dois produtos de exemplo: Inicial e Ilimitado. Você publica uma API no portal do desenvolvedor associando a API a um produto. Você pode incluir várias APIs em um produto e oferecer assinaturas de produtos para desenvolvedores por meio do portal do desenvolvedor. Para adicionar essa API a outro produto, digite ou selecione o nome do produto. Repita esta etapa para adicionar a API a vários produtos. Você também pode adicionar APIs a produtos posteriormente na página Configurações . Para obter mais informações sobre produtos, consulte Criar e publicar um produto.
   Gateways	Gerido	Gateways de API que expõem a interface de programação. Este campo está disponível apenas em serviços de nível Developer e Premium . Gerenciado indica o gateway integrado no serviço API Management e alojado pela Microsoft em Azure. Os gateways auto-geridos estão disponíveis apenas nas camadas de serviço Premium e Desenvolvedor. Você pode implantá-los no local ou em outras nuvens. Se não selecionares nenhum gateway, a API não está disponível e os teus pedidos de API não têm sucesso.
   Versão desta API?	Selecionar ou desmarcar	Para obter mais informações, consulte Publicar várias versões da API.

5. Selecione Criar para criar sua API.

Se tiver dificuldades em importar uma definição de API, consulte restrições de importação de API e problemas conhecidos.

Visualizar e modificar as definições da API

Depois de importar a sua API, pode visualizar e modificar as suas definições e operações no Azure portal.

1. Na sua instância de gestão de API, em APIs no menu lateral, selecione APIs.

2. Selecione a sua API importada (por exemplo, Swagger Petstore).

3. Selecione o separador Design para visualizar e modificar operações de API na especificação OpenAPI, incluindo:

   • Detalhes da operação, como URL, método e descrição
   • Definições de pedidos e respostas
   • Políticas para modificar pedidos e respostas

4. Selecione o separador Definições para visualizar e modificar detalhes de configuração da API, incluindo:

   • Nome de exibição, nome e descrição
   • URL de serviço web (serviço backend), esquema de URL e sufixo URL API
   • Produtos, etiquetas e versionamento
   • Definições mais avançadas, como requisitos de subscrição, segurança e monitorização

À medida que percorre os tutoriais de API Management, aprende mais sobre como configurar as definições da API. Pode atualizar estas definições a qualquer momento para personalizar a configuração da sua API.

Teste a nova API no Azure portal

Pode chamar as operações da API diretamente a partir do Azure portal, que oferece uma forma conveniente de visualizar e testar as operações. Na consola de testes do portal, as APIs são chamadas, por defeito, utilizando uma chave da subscrição incorporada all-access. Você também pode testar chamadas de API usando uma chave de assinatura associada a um produto.

1. Na sua API Management instância, selecione APIs>APIs>Swagger Petstore.

2. Selecione a guia Teste e, em seguida, selecione Localiza animais de estimação por status. A página mostra o parâmetro de consulta status. Selecione um dos valores disponíveis, como pendente. Você também pode adicionar parâmetros de consulta e cabeçalhos aqui.

   Na secção HTTP da solicitação, o cabeçalho Ocp-Apim-Subscription-Key é preenchido automaticamente, visível ao selecionar o ícone "olho".

3. Selecione Enviar.

   

   O backend responde com 200 OK e alguns dados.

Como a API Management encaminha pedidos

A API Management atua como uma porta de entrada entre os seus clientes API e os seus serviços backend. Quando um cliente faz um pedido a uma API gerida pela API Management, o encaminhamento segue este padrão:

URL do pedido do cliente:
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

A API Management encaminha o pedido para o serviço backend usando este padrão:

URL do serviço backend:
[Web service URL] + [Operation endpoint]

A tabela seguinte descreve cada parâmetro de roteamento no contexto do exemplo da API Petstore usado neste tutorial:

Exemplo: Encontrar animais de estimação por estado

Usando a API da Petstore importada neste tutorial:

• Cliente chama o API Management:
  https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

  • URL do gateway de gestão de API: https://apim-hello-world.azure-api.net
  • Sufixo URL da API: petstore
  • Endpoint da operação: /pet/findByStatus

• API Management encaminhamentos para o backend:
  https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

  • URL do serviço web: https://petstore3.swagger.io/api/v3
  • Endpoint da operação: /pet/findByStatus (igual à definição API Management)

Próximo passo

Avance para o próximo tutorial para aprender a criar e publicar um produto: