Partilhar via

Importar APIs para o seu centro de API a partir do Azure API Management

  • Artigo

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

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

  • Opção 1 - Exportar 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 maneiras de importar uma definição de API exportada do Gerenciamento de API incluem:

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

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 as partes interessadas a descobrir, entender e consumir a API.

Gorjeta

Você também pode configurar a sincronização automática de APIS do Gerenciamento de API para o seu centro de APIs. Para obter mais informações, consulte Vincular uma instância de gerenciamento de API para sincronizar APIs com seu centro de APIs.

Pré-requisitos

  • Um centro de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de APIs.

  • 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 seu centro de APIs.

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

    Nota

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

    Consulte as notas de versão para obter as alterações e atualizações mais recentes no apic-extension.

    Nota

    Os exemplos de comandos da CLI do Azure neste artigo podem ser executados no PowerShell ou em um shell bash. Quando necessário devido à sintaxe variável diferente, exemplos de comandos separados são fornecidos para os dois shells.

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

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

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

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

#! /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 API para um URL

No exemplo a seguir, az apim api export exporta a API com identificador my-api no formato OpenApiJson para uma URL no armazenamento do Azure. O URL fica 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 em seu centro de API a partir da definição de API exportada

Você pode registrar uma nova API em seu centro de API a partir da definição exportada usando o comando az apic api register .

O exemplo a seguir registra uma API no centro de API myAPICenter a partir 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 definição de API para uma API existente no 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 de API associada v1-0-0 e entidade de definição openapi em seu centro de API. Caso contrário, consulte Adicionar APIs ao seu centro de APIs.

#! /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 estão as etapas para importar APIs da sua instância de Gerenciamento de API para o seu 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 APIs, 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-apimo , o seguinte acontece automaticamente:

Adicionar uma identidade gerenciada em seu 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 gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

Os exemplos a seguir mostram como configurar uma identidade gerenciada atribuída ao sistema usando o portal do Azure ou a CLI do Azure. Em um alto nível, as etapas de configuração são semelhantes para uma identidade gerenciada atribuída pelo usuário.

  1. No portal, navegue até o centro de APIs.
  2. No menu à esquerda, em Segurança, selecione Identidades gerenciadas.
  3. Selecione Sistema atribuído e defina o status como Ativado.
  4. Selecione Guardar.

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

Para permitir a importação de APIs, atribua à identidade gerenciada do seu centro de API a função Leitor de Serviço de Gerenciamento de API em sua instância de Gerenciamento de API . Você pode usar o portal ou a CLI do Azure.

  1. No portal, navegue até sua instância de Gerenciamento de API.
  2. No menu à esquerda, selecione Controle de acesso (IAM).
  3. Selecione + Adicionar atribuição de função.
  4. Na página Adicionar atribuição de função, defina os valores da seguinte forma:
    1. Na guia Função - Selecione API Management Service Reader.
    2. Na guia Membros, em Atribuir acesso a - Selecione Identidade> gerenciada+ Selecionar membros.
    3. Na página Selecionar identidades gerenciadas - Selecione a identidade gerenciada atribuída ao sistema do seu centro de API que você adicionou na seção anterior. Clique em Selecionar.
    4. Selecione Rever + atribuir.

Importar APIs do Gerenciamento de API

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

Nota

  • Esse comando depende de uma identidade gerenciada configurada em seu centro de API que tenha permissões de leitura para a instância de Gerenciamento de API. Se você não adicionou ou configurou uma identidade gerenciada, consulte Adicionar uma identidade gerenciada em seu centro de API anteriormente neste artigo.

  • Se o seu centro de API tiver várias identidades gerenciadas, o comando procurará primeiro uma identidade atribuída ao sistema. Se nenhuma for encontrada, ele selecionará a primeira identidade atribuída pelo usuário na lista.

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

No comando a seguir, substitua os nomes do centro de APIs, do grupo de recursos do centro de APIs, da instância de Gerenciamento de API e do grupo de recursos da instância. Use * para especificar todas as APIs da instância de 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 '*'

Nota

Se sua instância de Gerenciamento de API tiver um grande número de APIs, a importação para o centro de APIs pode levar algum tempo.

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 APIs, do grupo de recursos do centro de APIs, da instância de Gerenciamento de API e do grupo de recursos da instância. Passe um nome de API, como petstore-api usar o --apim-apis parâmetro.

#! /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'

Nota

Especifique um nome de API usando o nome do recurso da API na instância de Gerenciamento de API, não o nome para exibição. Exemplo: petstore-api em vez de Petstore API.

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

Conteúdos relacionados