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 mais informações, veja Get started with 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 Autenticar no Azure usando a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a 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, importa-se a especificação OpenAPI para a API Petstore de código aberto, mas pode substituir por uma especificação OpenAPI da sua escolha.

Portais

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><a sua API>>Todas as operações.
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, a Gestão de API preenche automaticamente um cabeçalho Ocp-Apim-Subscription-Key e configura a chave de subscrição da subscrição de acesso total interna. Essa chave permite o acesso a todas as APIs na instância de Gerenciamento de API. Opcionalmente, pode mostrar 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 endpoints 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 a partir de APIs que são 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
• Funções do Azure
• Aplicativos Lógicos do Azure
• Azure Service Fabric

Nota

Quando você importa uma API, as operações são anexadas à sua API atual.

Para acrescentar uma API a uma API existente:

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 selecione APIs> APIs no menu à esquerda.

   

3. Selecione as reticências (...) ao lado da API à qual você deseja acrescentar outra API.

4. Selecione Importar no menu deslizante:

   

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

Conteúdo relacionado

• Limitações de importação de API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importe uma API SOAP e converta-a 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 GraphQL e configurar resolvers de campo
• Importar uma API de aplicativo de função
• Importar uma API de aplicativo lógico
• Importar um serviço do Service Fabric
• Importar uma API do Azure AI Foundry
• Importar uma API OpenAI do Azure
• Importar uma API LLM
• Importar uma API OData
• Importar metadados do SAP OData
• Importar uma API gRPC
• Editar uma API