Importar uma especificação de OpenAPI

APLICA-SE A: Todas as camadas de gerenciamento de API

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

Neste artigo, vai aprender a:

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

Nota

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 tiver uma, conclua o seguinte 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, consulte Guia de início rápido para Bash no Azure Cloud Shell.

    

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

• Azure PowerShell

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

Importar uma API de back-end

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

Portal

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

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

3. Em Criar a partir da definição, selecione OpenAPI.

   

4. Insira as configurações da API. Você pode definir os valores durante a criação ou configurá-los mais tarde, indo para 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 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 --specification-path parâmetro.

# 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 cmdlet Import-AzApiManagementApi Azure PowerShell para importar uma especificação 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 -SpecificationPath parâmetro.

# 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 .

Ver e editar a especificação OpenAPI

No portal, use o editor de especificações OpenAPI para exibir, validar ou editar a especificação da API que você importou.

Para usar o editor de especificações OpenAPI:

1. No portal do Azure, navegue até sua instância de Gerenciamento de API.
2. No menu à esquerda, em APIs, selecione APIs<>para suas operações de API>>Todos.
3. Na guia Design, em Frontend, selecione OpenAPI Specification editor (ícone de lápis). Você pode abrir a especificação no formato JSON ou YAML.
4. Revise ou edite a especificação conforme necessário. Salve suas alterações.

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

Você pode configurar políticas de validação do Gerenciamento de API para validar solicitações e respostas (ou elementos delas) 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.

Teste a nova API no portal

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

1. Selecione a API que criou no passo anterior.

2. Selecione o separador Teste.

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

   Nota

   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 de acesso total interna. Essa chave permite o acesso a todas as APIs 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âmetros de consulta, valores de cabeçalho ou um corpo de 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.

   Gorjeta

   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 de Gerenciamento de API, que a encaminha para o back-end. Este proxy usa o endereço IP público 13.91.254.72 e só pode alcançar pontos de extremidade públicos. Se quiser enviar uma solicitação diretamente do navegador para o serviço de Gerenciamento de API, selecione Ignorar proxy CORS. Use essa opção quando quiser usar o console de teste e seu gateway de Gerenciamento de API estiver isolado na rede ou não permitir tráfego do proxy CORS.

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

Anexar outras APIs

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

• Uma especificação OpenAPI
• UMA API SOAP
• Uma API GraphQL
• Um Aplicativo Web hospedado no Serviço de Aplicativo do Azure
• Aplicação de Função do Azure
• Azure Logic Apps
• Azure Service Fabric

Anexe uma API diferente à sua API existente usando as etapas a seguir.

Nota

Quando importar outra API, as operações são anexadas à API atual.

1. Aceda à sua instância de API Management do Azure no portal do Azure.

   

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

   

3. Clique em ... junto à API à qual quer anexar outra API.

4. Selecione Importar no menu pendente.

   

5. Selecione um serviço a partir do qual quer importar uma API.

   

Tópicos relacionados

• Limitações de importação de API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API de SOAP e converter em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API de aplicativo de contêiner
• Importar uma API WebSocket
• Importar uma GraphQL API
• Importar um esquema de GraphQL e configurar resoluções de campos
• Importar uma Aplicação de Função do Azure
• Importar uma Aplicação Lógica do Azure
• Importar um serviço do Service Fabric
• Importar uma API OpenAI do Azure
• Importar uma API OData
• Importar metadados do SAP OData
• Importar uma API gRPC
• Editar uma API

Próximos passos

• Criar e publicar um produto
• Transformar e proteger a sua API