Sincronizar APIs de uma instância de Gerenciamento de API

Este artigo mostra como integrar uma instância de Gerenciamento de API para que as APIs das instâncias sejam continuamente mantidas atualizadas em seu inventário do centro de APIs .

Tip

Este artigo explica como integrar uma instância de Gerenciamento de API do seu centro de API. Como alternativa, configure rapidamente a integração diretamente de uma instância de Gerenciamento de API. No menu esquerdo da sua instância, em APIs, selecione Central de APIs e selecione uma central de API de destino em sua assinatura para sincronizar APIs.

Sobre a integração de uma instância de Gerenciamento de API

Embora você possa usar a CLI do Azure para importar APIs sob demanda do Gerenciamento de API do Azure para a Central de APIs do Azure, a integração (vinculação) de uma instância de Gerenciamento de API permite a sincronização contínua para que o inventário de API permaneça atualizado. O Centro de API do Azure também pode sincronizar APIs de fontes, incluindo o Amazon API Gateway.

Quando você integra uma instância de Gerenciamento de API como uma fonte de API, acontece o seguinte:

1. Todas as APIs e, opcionalmente, as definições de API (especificações) da instância de Gerenciamento de API são adicionadas ao inventário do centro de APIs. Os servidores MCP no Gerenciamento de API são incluídos nas APIs adicionadas ao inventário.
2. Você configura um ambiente do tipo Gerenciamento de API do Azure no centro de APIs.
3. Uma implantação associada é criada para cada definição de API sincronizada do Gerenciamento de API.

As APIs de Gerenciamento de API são sincronizadas automaticamente com o centro de APIs sempre que as configurações das APIs existentes são alteradas (por exemplo, novas versões são adicionadas), novas APIs são criadas ou APIs são excluídas. Essa sincronização é unidirecional do Gerenciamento de API para o centro de API do Azure, o que significa que as atualizações de API no centro de API não são sincronizadas de volta à instância de Gerenciamento de API.

Note

• Há limites para o número de instâncias integradas de Gerenciamento de API (fontes de API).
• Uma instância integrada de Gerenciamento de API pode ser configurada em uma rede virtual.
• As atualizações de API no Gerenciamento de API normalmente são sincronizadas com o seu centro de API em poucos minutos, mas a sincronização pode levar até 24 horas.
• As definições de API também são sincronizadas com o centro de API se você selecionar a opção para incluí-las durante a integração.

Entidades sincronizadas a partir do Gerenciamento de API

Você pode adicionar ou atualizar propriedades e documentação de metadados às APIs sincronizadas em seu centro de APIs para ajudar as partes interessadas a descobrir, entender e consumir as APIs. Saiba mais sobre as propriedades de metadados internas e personalizadas do Centro de API do Azure.

A tabela a seguir mostra as propriedades da entidade que podem ser modificadas na Central de APIs do Azure e as propriedades definidas com base em seus valores na fonte da API.

Entity	Propriedades configuráveis no Centro de API	Propriedades determinadas na origem da API integrada
API	resumo lifecycleStage termsOfService licença externalDocumentation customProperties	title description kind
Versão da API	lifecycleStage	title definições (se sincronizadas)
Environment	title description tipo server.managementPortalUri inclusão customProperties	server.type
Deployment	title description servidor state customProperties	server.runtimeUri

Note

As IDs de recurso e de sistema para entidades sincronizadas com a Central de APIs do Azure são geradas automaticamente e não podem ser alteradas.

Prerequisites

• 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 instância de Gerenciamento de API do Azure, na mesma assinatura ou em uma assinatura diferente. A instância deve estar no mesmo diretório.

• Para a 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 o 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 você estiver usando uma instalação local, entre na CLI do Azure usando 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 az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

  Note

  az apic comandos requerem 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. Alguns recursos podem exigir uma visualização ou uma versão específica da extensão.

  Note

  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.

Habilite uma identidade gerenciada em seu centro de API

Para esse cenário, sua central de API usa uma identidade gerenciada para acessar recursos do Azure. Dependendo das suas necessidades, habilite uma identidade gerenciada atribuída pelo sistema ou uma ou mais identidades gerenciadas atribuídas pelo usuário.

Os exemplos a seguir mostram como habilitar 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.

Portal

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.

Defina a identidade atribuída ao sistema em seu centro de API usando o seguinte comando az apic update . Substitua os nomes do seu centro de API e grupo de recursos:

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

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.

Portal

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 Leitor de 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 ao sistema do seu centro de API que você adicionou na seção anterior. Clique em Selecionar.
   4. Selecione Rever + atribuir.

1. Obtenha o identificador principal da identidade. Para uma identidade atribuída pelo sistema, use o comando az apic show.

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Obtenha o ID do recurso da sua instância de Gerenciamento de API usando o comando az apim show .

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Atribua à identidade gerida a função Leitor de Serviço de Gerenciamento de API na sua instância de Gerenciamento de API usando o comando az role assignment create.

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

Integrar uma instância de gerenciamento de API

Você pode integrar uma instância de Gerenciamento de API usando o portal ou a CLI do Azure.

Portal

1. No portal, navegue até o centro de APIs.
2. Em Plataformas, selecione Integrações.
3. Selecione + Nova integração>a partir do Azure API Management.
4. Na página Integrar seu Serviço de Gerenciamento de API do Azure :
   1. Selecione se deseja sincronizar todas as APIs da instância de Gerenciamento de API ou apenas as APIs que estão em um espaço de trabalho de Gerenciamento de API.
   2. Selecione o serviço Assinatura, Grupo de recursos e Gerenciamento de API do Azure que você deseja integrar. Se você quiser sincronizar apenas APIs de um espaço de trabalho, faça uma seleção em Escolher um espaço de trabalho.
   3. Em Detalhes da integração, insira um identificador. Se você ainda não configurou uma identidade gerenciada com acesso à instância de Gerenciamento de API, habilite Configurar automaticamente a identidade gerenciada e atribuir permissões. Essa seleção atribui automaticamente à identidade gerenciada atribuída ao sistema do centro de API as permissões necessárias para sincronizar APIs da instância de Gerenciamento de API.
   4. Em Detalhes do ambiente, insira um Título do ambiente (nome), Tipo de ambiente e Descrição opcional.
   5. Em Detalhes da API:
      1. Selecione um ciclo de vida para as APIs sincronizadas. (Você pode atualizar esse valor para as APIs depois que elas forem adicionadas ao seu centro de APIs.)
      2. Opcionalmente, selecione se deseja incluir definições de API com as APIs sincronizadas.
5. Selecione Criar.

Execute o comando az apic integration create apim para integrar uma instância de Gerenciamento de API ao seu centro de API.

• Forneça os nomes do grupo de recursos, do centro de API e da integração.

• Se a instância de Gerenciamento de API e o centro de API estiverem no mesmo grupo de recursos, você poderá fornecer o nome da instância de Gerenciamento de API como o valor de ; caso contrário, forneça a ID de recurso do azure-apimAzure.

az apic integration create apim \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <apim-integration-name> \
    --azure-apim <apim-instance-name>

A instância de Gerenciamento de API é integrada como um ambiente em seu centro de API. As APIs de Gerenciamento de API são sincronizadas com o inventário do centro de APIs.

Excluir uma integração

Embora uma fonte de API esteja integrada, você não pode excluir APIs sincronizadas do seu centro de APIs. Se precisar, você pode excluir a integração. Quando você exclui uma integração:

• As APIs sincronizadas no inventário do centro de APIs são excluídas
• O ambiente e as implantações associadas à origem da API são excluídos

Você pode excluir uma integração usando o portal ou a CLI do Azure.

Portal

1. No portal, navegue até o centro de APIs.
2. Em Ativos, selecione Integrações de ambientes>(visualização).
3. Selecione a integração e, em seguida, selecione Excluir (ícone da lixeira).

Execute o comando az apic integration delete (preview) para excluir uma integração. Forneça os nomes do grupo de recursos, do centro de API e da integração.

az apic integration delete \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <integration-name> \

Conteúdo relacionado

• Gerenciar inventário de API com comandos da CLI do Azure
• Importar APIs do Gerenciamento de API para o centro de API do Azure
• Registre-se e descubra servidores MCP em seu centro de API
• Documentação do Azure API Management