Compartilhar via

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

  • Artigo

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:

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

Dica

Também é possível configurar a sincronização automática do APIS do Gerenciamento de API para o centro de API. Para obter mais informações, consulte Vincular uma instância de Gerenciamento de API para sincronizar APIs ao centro de 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:

    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.

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

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.

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.
  2. No menu à esquerda, selecione Controle de acesso (IAM) .
  3. Escolha Adicionar atribuição de função.
  4. Na página Adicionar atribuição de função, defina os valores da seguinte maneira:
    1. Na guia Função – Selecione Leitor do Serviço de Gerenciamento de API.
    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 pelo sistema do seu centro de API que você adicionou na seção anterior. Clique em Selecionar.
    4. Selecione Examinar + atribuir.

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.

Observação

  • 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 centro de API tiver várias identidades gerenciadas, o comando procurará primeiro uma identidade atribuída pelo sistema. Se nenhuma for encontrada, ele escolherá 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 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 '*'

Observação

Se sua instância de Gerenciamento de API tiver um grande número de APIs, a importação para o centro de API poderá 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 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'

Observação

Especifique um nome de API usando o nome do recurso de API na instância do Gerenciamento de API, não o nome de exibição. Exemplo: petstore-api em vez de 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