Importar APIs para o seu Centro de API do Gerenciamento de API do Azure

Este artigo mostra como importar (adicionar) APIs de uma instância do Gerenciamento de API do Azure para o seu centro de API usando a CLI do Azure. Adicionar APIs do Gerenciamento de API ao inventário de API ajuda a torná-las detectáveis e acessíveis para os desenvolvedores, gerentes de programas de API e outros stakeholders em sua organização.

Este artigo mostra duas opções para usar a CLI do Azure para adicionar APIs ao seu centro de API do Gerenciamento de API:

• Opção 1 – Exporte uma definição de API de uma instância de Gerenciamento de API usando o comando az apim api export. Em seguida, importe a definição para o centro de API.

  As possíveis formas de importar uma definição de API exportada do Gerenciamento de API incluem:

  • Executar api az apic register para registrar uma nova API no centro de API.
  • Executar az apic api definition import-specification para importar a definição de API para uma API existente.

• Opção 2 – Importe as APIs diretamente do Gerenciamento de API para o centro de API usando o comando az apic import-from-apim.

Depois de importar definições de API ou APIs do Gerenciamento de API, você pode adicionar metadados e documentação em seu centro de API para ajudar os stakeholders a descobrir, entender e consumir a API.

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você não criou um, consulte Início Rápido: criar seu centro de API.

• Uma ou mais instâncias do Gerenciamento de API do Azure, na mesma assinatura ou em uma assinatura diferente. Quando você importa APIs diretamente do Gerenciamento de API, a instância de Gerenciamento de API e o Centro de API devem estar no mesmo diretório. Se você ainda não criou uma, consulte Criar uma instância de Gerenciamento de API do Azure.

• Uma ou mais APIs gerenciadas em sua instância de Gerenciamento de API que você deseja adicionar ao centro de API.

• Para a 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.

  Observação

  Os comandos az apic exigem a extensão da CLI do Azure apic-extension. Se você não tiver usado comandos az apic, a extensão poderá ser instalada dinamicamente quando você executar seu primeiro comando az apic ou instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.

  Confira as notas sobre a versão para ver as últimas alterações e atualizações no apic-extension.

  Observação

  Os exemplos de comando da CLI do Azure incluídos neste artigo podem ser executados no PowerShell ou em um shell do Bash. Sempre que necessário, devido às diferentes sintaxes variáveis, são fornecidos exemplos de comando separados para os dois shells.

Opção 1: exportar uma definição de API do Gerenciamento de API e importá-la para o centro de API

Primeiro, exporte uma API de sua instância de Gerenciamento de API para uma definição de API usando o comando az apim api export. Dependendo do seu cenário, você pode exportar a definição de API para um arquivo local ou uma URL.

Exportar a API para um arquivo de definição de API local

O comando de exemplo a seguir exporta a API com o identificador my-api na instância myAPIManagement da API. A API é exportada no formato OpenApiJson para um arquivo de definição do OpenAPI local no caminho que você especifica.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Exportar a API para uma URL

No exemplo a seguir, api do az apim export exporta a API com o identificador my-api no formato OpenApiJson para uma URL no armazenamento do Azure. A URL está disponível por aproximadamente 5 minutos. Aqui, o valor da URL é armazenado na variável $link.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Registrar a API no centro de API da definição da API exportada

Você pode registrar uma nova API no centro de API na definição exportada usando o comando az apic api register.

O exemplo a seguir registra uma API no centro de API myAPICenter de um arquivo de definição OpenAPI local chamado definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Importar uma definição de API para uma API existente em seu centro de API

O exemplo a seguir usa o comando az apic api definition import-specification para importar uma definição de API para uma API existente no centro de API myAPICenter. Aqui, a definição de API é importada de uma URL armazenada na variável $link.

Este exemplo pressupõe que você tenha uma API chamada my-api e uma versão da API associada v1-0-0 e a entidade de definição openapi no centro de API. Se não tiver, consulte Adicionar APIs ao centro de API.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Opção 2: Importar APIs diretamente da instância de Gerenciamento de API

A seguir você verá as etapas usadas para importar as APIs da sua instância do Gerenciamento de API para o centro de API usando o comando az apic import-from-apim. Esse comando é útil quando você deseja importar várias APIs do Gerenciamento de API para o centro de API, mas também pode usá-lo para importar uma única API.

Quando você adiciona APIs de uma instância de Gerenciamento de API ao seu centro de API usando az apic import-from-apim, o seguinte acontece automaticamente:

• As informações sobre versões, definições e implantação de cada API são copiadas para o seu centro de API.
• A API recebe um nome de API gerado pelo sistema no centro de API. Ele mantém seu nome de exibição (título) do Gerenciamento de API.
• O Estágio do ciclo de vida da API é definido como Design.
• O Gerenciamento de API do Azure é adicionado como um ambiente.

Adicionar uma identidade gerenciada no centro de API

Para esse cenário, seu centro de API usa uma identidade gerenciada para acessar APIs em sua instância de Gerenciamento de API. Dependendo das suas necessidades, configure uma identidade gerida atribuída pelo sistema ou uma ou mais identidades geridas atribuídas pelo utilizador.

Os exemplos a seguir mostram como configurar uma identidade gerenciada atribuída pelo sistema usando o portal do Azure ou a CLI do Azure. A um nível elevado, os passos de configuração são semelhantes para uma identidade gerida atribuída pelo utilizador.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Atribuir a identidade gerenciada à função Leitor do Serviço de Gerenciamento de API

Para permitir a importação de APIs, atribua a identidade gerenciada do centro de API a função Leitor do Serviço de Gerenciamento de API em sua instância de Gerenciamento de API. É possível usar o portal ou a CLI do Azure.

Importar APIs do Gerenciamento de API

Use o comando az apic import-from-apim para importar uma ou mais APIs da sua instância do Gerenciamento de API para o centro de API.

Importar todas as APIs de uma instância de Gerenciamento de API

No comando a seguir, substitua os nomes do centro de API, o grupo de recursos do centro de API, a instância de Gerenciamento de API e o grupo de recursos da instância. Use * para especificar todas as APIs da instância do Gerenciamento de API.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

Importar uma API específica de uma instância de Gerenciamento de API

Especifique uma API para importar usando seu nome da instância de Gerenciamento de API.

No comando a seguir, substitua os nomes do centro de API, o grupo de recursos do centro de API, a instância de Gerenciamento de API e o grupo de recursos da instância. Transmita um nome de API, como petstore-api, usar o parâmetro --apim-apis.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

Depois de importar as APIs do Gerenciamento de API, você pode exibir e gerenciar as APIs importadas em seu centro de API.

Conteúdo relacionado

• Referência da CLI do Azure para o Centro de API do Azure
• Referência da CLI do Azure para o Gerenciamento de API
• Gerenciar o inventário de API com comandos da CLI do Azure
• Atribuir funções do Azure a uma identidade gerenciada
• Documentação do Gerenciamento de API do Azure