Importar uma especificação de OpenAPI

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo mostra como importar uma API de back-end de “Especificação de OpenAPI” para o Gerenciamento de API do Azure usando várias ferramentas. O artigo também mostra como testar a API do Gerenciamento de API.

Neste artigo, você aprenderá como:

• Importar uma especificação de OpenAPI usando o portal do Azure, a CLI do Azure ou o Azure PowerShell
• Testar a API no Portal do Azure

Observação

As limitações de importação de API estão documentadas em restrições de importação de API e problemas conhecidos.

Pré-requisitos

• Uma instância de Gerenciamento de API. Se você ainda não tem uma, conclua o seguinte guia de início rápido: Criar uma instância de Gerenciamento de API do Azure.

• CLI do Azure

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

    

  • Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

    • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

• PowerShell do Azure

  • Se você optar por usar o Azure PowerShell localmente:
    • Instale a versão mais recente do módulo do Az PowerShell.
    • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
  • Se você optar por usar o Azure Cloud Shell:
    • Confira Visão geral do Azure Cloud Shell para obter mais informações.

Importar uma API de back-end

Para este exemplo, você importa a Especificação de OpenAPI para a API Petstore de código aberto, mas pode substituir uma especificação de OpenAPI de sua escolha.

Portal

1. No portal do Azure, navegue até a instância do Gerenciamento de API.

2. No menu à esquerda, selecione APIs >+Adicionar API.

3. Em Criar com base na definição, selecione OpenAPI.

   

4. Insira as configurações de API. Você pode definir os valores durante a criação ou configurá-los mais tarde, acessando a guia Configurações. As configurações são explicadas no tutorial Importar e publicar sua primeira API.

5. Selecione Criar.

CLI do Azure

O exemplo a seguir usa o comando az apim api import para importar uma especificação de API da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro --specification-path.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Depois de importar a API, se necessário, você pode atualizar as configurações usando o comando az apim api update.

PowerShell

O exemplo a seguir usa o comando Import-AzApiManagementApi do cmdlet do Azure PowerShell para importar uma especificação de OpenAPI da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro -SpecificationPath.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Depois de importar a API, se necessário, você pode atualizar as configurações usando o cmdlet Set-AzApiManagementApi.

Exibir e editar especificação de OpenAPI

No portal, use o editor de especificação de OpenAPI para exibir, validar ou editar a especificação da API importada.

Para usar o editor de especificação de OpenAPI:

1. No portal do Azure, navegue até a instância do Gerenciamento de API.
2. No menu do lado esquerdo, em APIs, selecione APIs><sua API>>Todas as operações.
3. Na guia Design, em Front-end, selecione Editor de especificação de OpenAPI (ícone de lápis). Você pode abrir a especificação no formato JSON ou YAML.
4. Examine ou edite a especificação conforme necessário. Salve suas alterações.

Validar em relação a um esquema de especificação de OpenAPI

Você pode configurar as políticas de validação do Gerenciamento de API para validar solicitações e respostas (ou respectivos elementos) em relação ao esquema em uma especificação OpenAPI. Por exemplo, use a política validate-content para validar o tamanho ou o conteúdo de uma solicitação ou corpo de resposta.

Testar a nova API no portal

As operações podem ser chamadas diretamente do portal, que fornece uma maneira conveniente para administradores exibirem e testarem as operações de uma API.

1. Selecione a API que você criou na etapa anterior.

2. Selecione a guia Testar.

3. Selecione uma operação. A página exibe os campos dos parâmetros de consulta e os campos dos cabeçalhos.

   Observação

   No console de teste, o Gerenciamento de API preenche automaticamente um cabeçalho Ocp-Apim-Subscription-Key e configura a chave de assinatura da assinatura interna de acesso total. Essa chave permite o acesso a todas as API na instância de Gerenciamento de API. Opcionalmente, exiba o cabeçalho Ocp-Apim-Subscription-Key selecionando o ícone "olho" ao lado da Solicitação HTTP.

4. Dependendo da operação, insira valores de parâmetro de consulta, valores de cabeçalho ou um corpo da solicitação. Selecione Enviar.

   Quando o teste é bem-sucedido, o back-end responde com um código de resposta HTTP bem-sucedido e alguns dados.

   Dica

   Por padrão, o console de teste envia uma solicitação para o proxy CORS do Gerenciamento de API, que encaminha a solicitação para a instância Gerenciamento de API, que a encaminha para o back-end. Esse proxy usa o endereço de IP público 13.91.254.72 e só pode alcançar pontos de extremidade públicos. Se você quiser enviar uma solicitação diretamente do navegador para o serviço Gerenciamento de API, selecione Ignorar proxy CORS. Use essa opção quando quiser usar o console de teste e o gateway do Gerenciamento de API estiver isolado na rede ou não permitir o tráfego do proxy CORS.

Para depurar uma API, confira o Tutorial: Depurar suas APIs usando o rastreamento de solicitações.

Acrescentar outras APIs

Você pode compor uma API de APIs expostas por diferentes serviços, incluindo:

• Uma especificação do OpenAPI
• Uma API SOAP
• Uma API da GraphQL
• Um aplicativo Web hospedado no Serviço de Aplicativo do Azure
• Aplicativo de Funções do Azure
• Aplicativos Lógicos do Azure
• Azure Service Fabric

Acrescente uma API diferente da API existente usando as etapas a seguir.

Observação

Ao importar outra API, as operações são acrescentadas à sua API atual.

1. Vá para sua instância de Gerenciamento de API do Azure no portal do Azure.

   

2. Selecione APIs na página Visão geral ou no menu à esquerda.

   

3. Clique em ... ao lado da API à qual você deseja acrescentar outra API.

4. Selecione Importar no menu suspenso.

   

5. Selecione um serviço de onde será importada a API.

   

Tópicos relacionados

• Limitações de importação da API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API SOAP e converter em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API do Aplicativo de Contêiner
• Importar uma API WebSocket
• Importar uma API do GraphQL
• Importar um esquema do GraphQL e configurar resolvedores de campo
• Importar um Aplicativo de Funções do Azure
• Importar um Aplicativo Lógico do Azure
• Importar um serviço do Service Fabric
• Importar uma API do OpenAI do Azure
• Importar uma API de OData
• Importar metadados do SAP OData
• Importar uma API do gRPC
• Editar uma API

Próximas etapas

• Criar e publicar um produto
• Transformar e proteger uma API publicada