Sincronizar ativos API de um repositório Git para o Azure API Center

Este artigo descreve como integrar um repositório Git com Azure API Center para sincronizar automaticamente ativos da API como skills, agents e MCP no seu inventário de APIs. Ao ligar um repositório Git, pode manter o inventário do seu centro de API atualizado sem ter de registar ou atualizar manualmente cada ativo.

Quando integra um repositório Git:

• O seu centro de API cria um ambiente que representa o repositório como uma fonte de ativos.
• O API Center sincroniza regularmente a informação dos ativos do repositório para o inventário do API Center.

Pré-requisitos

• Um centro de API. Se ainda não tem um centro de APIs, consulte o início rápido para Criar um centro de APIs.

• Um repositório Git contendo os assets que queres sincronizar.

• Para repositórios não públicos, existe um token de acesso pessoal (PAT) para aceder ao repositório. O PAT deve ter as permissões apropriadas para ler o conteúdo do repositório. Para criar um PAT para o GitHub, veja Criar um token de acesso pessoal detalhado.

• Um cofre de chaves do Azure para armazenar o PAT, se for usado para acesso. Se precisar de criar um cofre de chaves, veja Quickstart: Crie um cofre de chaves usando o portal Azure. Para adicionar ou gerir segredos no cofre de chaves, precisas pelo menos do papel de Oficial de Segredos do Cofre de Chaves ou permissões equivalentes.

• Para CLI do Azure:

  • Usa o ambiente Bash em Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.

    

  • Se preferires executar comandos de referência de CLI localmente, instala o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o CLI do Azure num contentor Docker. Para mais informações, veja Como executar o CLI do Azure num contentor 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 exibidos no seu terminal. Para outras opções de iniciação de sessão, veja Autenticar para Azure usando CLI do Azure.

    • Quando solicitado, instale a extensão do CLI do Azure na primeira utilização. Para mais informações sobre extensões, veja Usar e gerir 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

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

Store PAT in Azure Key Vault

Se o seu repositório Git for privado, carregue manualmente e armazene de forma segura um PAT no Azure Key Vault que conceda acesso ao repositório. Quando integrares o repositório Git com o teu centro de API, configura a integração para usar este segredo.

Para obter mais informações, consulte Guia de início rápido: definir e recuperar um segredo do Cofre da Chave do Azure usando o portal do Azure.

Se não precisares de configurar um PAT, avança para Integrar um repositório Git.

Configure uma identidade gerida para o seu centro API

O seu centro de API usa uma identidade gerida para autenticar no Azure Key Vault e recuperar o PAT necessário para aceder ao repositório Git. Os procedimentos seguintes descrevem como configurar manualmente uma identidade gerida para o seu centro API e atribuir-lhe as permissões necessárias para aceder ao Key Vault.

Se não configurares a identidade gerida, o API Center pode configurá-la automaticamente quando integrares o repositório Git.

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, vai ao teu centro de API.
2. No menu lateral, em Segurança, selecione Identidades Geridas.
3. Selecione Sistema atribuído e defina o status como Ativado.
4. Selecione Guardar.

CLI do Azure

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 gerida à função Utilizador de Segredos do Cofre de Chaves

Para permitir a importação dos ativos, atribua à identidade gerida do seu centro API o papel de Utilizador Key Vault Secrets no seu Azure Key Vault. Você pode usar o portal ou a CLI do Azure.

Portal

1. No portal, vai ao teu cofre de chaves.
2. No menu da barra lateral, selecione controlo 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 aba Role, selecione Key Vault Secrets User.
   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 Verificar + atribuir.

CLI do Azure

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 do seu cofre de chaves usando o comando az keyvault show .

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

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

3. Atribua à identidade gerida a função de Utilizador de Segredos do Cofre de Chaves no seu cofre de chaves utilizando o comando az role assignment create.

   #! /bin/bash
   scope="${kvID:1}"
   
   az role assignment create \
       --role "Key Vault Secrets User" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "Key Vault Secrets User" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

Integrar um repositório Git

Para integrar um repositório Git:

1. No portal Azure, vai ao teu centro de API.

2. No menu lateral, selecione Plataformas>Integrações.

3. Selecione + Nova integração e escolha Do repositório Git.

4. Em Integrar o seu repositório Git, introduza a seguinte informação:

   Campo	Description
   Configurar o código-fonte do repositório Git
   URL do repositório	Introduza o URL do repositório Git que contém ficheiros de assets. Se desejar, especifique o ramo e a subpasta (por exemplo, https://github.com/<org>/<repo>/tree/main/skills).
   Fornecedor Git	Selecione o fornecedor (por exemplo, GitHub).
   Configuração do tipo de ativo	API Center configura um tipo de ativo skill predefinido com o padrão de ficheiro **/skill.md. Selecionar + Adicionar tipo de ativo para sincronizar um ou mais tipos de ativos.
   Token de acesso pessoal (PAT)	Se tiver um PAT armazenado no Azure Key Vault, clique em Select para navegar até ao segredo do Key Vault. Opcionalmente, selecione Configurar automaticamente identidade gerida e atribuir permissões caso não tenha configurado manualmente uma identidade gerida para aceder ao segredo do cofre de chaves.
   Detalhes da integração	Aceite o identificador de ligação gerado ou forneça um ID personalizado para o link de integração.
   Detalhes do ambiente
   Título do Ambiente	Introduza um nome amigável para o ambiente do repositório (por exemplo, repositório Git).
   Identificação	Introduza o nome de um recurso de ambiente (por exemplo, git-repository).
   Tipo de ambiente	Selecione o tipo de ambiente (por exemplo, Produção).
   Descrição	Opcionalmente, adiciona uma descrição do ambiente.
   Detalhes dos ativos
   Ciclo de vida	Selecione a fase do ciclo de vida para ativos sincronizados a partir do repositório (por exemplo, Design).

   

5. Selecione Criar.

O portal adiciona o ambiente ao seu centro de API. O portal adiciona os ativos do repositório ao inventário do centro API na página de Inventário>. Pode identificar os ativos ligados pelo ícone de ligação na lista.

Conteúdo relacionado

• Registe-se e descubra competências no seu inventário de APIs
• Conceitos-chave no Azure API Center