Sincronizzare gli asset API da un repository Git nel Centro API di Azure

Questo articolo descrive come integrare un repository Git con Azure Centro API per sincronizzare automaticamente gli asset API, ad esempio skills, agents e MCP server nell'inventario API. Connettendo un repository Git, è possibile mantenere aggiornato l'inventario del centro API senza registrare o aggiornare manualmente ogni asset.

Integrando un repository Git:

• Il centro API crea un ambiente che rappresenta il repository come origine degli asset.
• Centro API sincronizza regolarmente le informazioni sugli asset dal repository all'inventario del centro API.

Prerequisiti

• Un centro API. Se non si ha ancora un centro API, vedere la guida introduttiva per Creare un centro API.

• Repository Git contenente gli asset da sincronizzare.

• Per i repository non pubblici, un token di accesso personale (PAT) per accedere al repository. Il pat deve disporre delle autorizzazioni appropriate per leggere il contenuto del repository. Per creare un token di accesso personale personalizzato per GitHub, vedere Creare un token di accesso personale con granularità fine.

• Un Azure Key Vault per archiviare il PAT, se utilizzato per l'accesso. Se è necessario creare un insieme di credenziali delle chiavi, vedere Quickstart: Creare un insieme di credenziali delle chiavi usando il portale di Azure. Per aggiungere o gestire segreti nel Key Vault, è necessario almeno il ruolo Key Vault Secrets Officer o autorizzazioni equivalenti.

• Per la CLI di Azure:

  • È possibile utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione a Azure Cloud Shell.

    

  • Se preferisci eseguire localmente i comandi di riferimento della CLI, installa l'interfaccia della riga di comando di Azure. Se si esegue in Windows o macOS, è consigliabile eseguire interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire il interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se usi un'installazione locale, accedi all'interfaccia della riga di comando di Azure usando il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

    • Quando ti viene richiesto, installa l'estensione interfaccia della riga di comando di Azure al primo utilizzo. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con interfaccia della riga di comando di Azure.

    • Esegui az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, avviare az upgrade.

  Note

  È possibile eseguire esempi di comandi dell'interfaccia della riga di comando di Azure in questo articolo in PowerShell o in una shell bash. Se necessario, a causa di una sintassi di variabile diversa, vengono forniti esempi di comandi separati per le due shell.

Archiviare pat in Azure Key Vault

Se il repository Git è privato, archiviare e caricare manualmente un token di accesso personale (PAT) in Azure Key Vault che concede l'accesso al repository. Integrando il repository Git con il centro API, configurare l'integrazione per l'uso di questo segreto.

Per altre informazioni, vedere Guida introduttiva: impostare e recuperare un segreto da Azure Key Vault usando il portale di Azure.

Se non è necessario configurare un token di accesso personale, procedere con l'integrazione di un repository Git.

Configurare un'identità gestita per il centro API

Il centro API usa un'identità gestita per eseguire l'autenticazione in Azure Key Vault e recuperare il token di accesso personale necessario per accedere al repository Git. Le procedure seguenti descrivono come configurare manualmente un'identità gestita per il centro API e assegnargli le autorizzazioni necessarie per accedere all'insieme di credenziali delle chiavi.

Se non si configura l'identità gestita, il Centro API può configurarlo automaticamente quando si integra il repository Git.

Per questo scenario, il centro API usa un'identità gestita per accedere alle risorse di Azure. A seconda delle esigenze, abilitare un'identità gestita assegnata dal sistema o una o più identità gestite assegnate dall'utente.

Gli esempi seguenti illustrano come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure o l'interfaccia della riga di comando di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

Portal

1. Nel portale vai al centro API.
2. Nel menu della barra laterale, in Sicurezza, selezionare Identità gestite.
3. Selezionare Sistema assegnato e impostare lo stato su Sì.
4. Seleziona Salva.

interfaccia della riga di comando di Azure

Impostare l'identità assegnata dal sistema nel centro API usando il comando az apic update seguente. Sostituire i nomi del centro API e del gruppo di risorse:

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

Assegnare l'identità gestita al ruolo Utente di Segreti di Key Vault

Per consentire l'importazione degli asset, assegna l'identità gestita del centro API al ruolo Utente dei segreti di Key Vault nel tuo Azure Key Vault. È possibile usare il portale o l'interfaccia della riga di comando di Azure.

Portal

1. Nel portale, andare all'insieme di credenziali delle chiavi.
2. Nel menu della barra laterale selezionare Controllo di accesso (IAM).
3. Selezionare + Aggiungi assegnazione di ruolo.
4. Nella pagina Aggiungi assegnazione di ruolo, impostare i valori come segue:
   1. Nella scheda Role selezionare Utente segreti di Key Vault.
   2. Nella scheda Membri, in Assegnare l'accesso a - Selezionare Identitàgestita>+ Seleziona membri.
   3. Nella pagina Seleziona le identità gestite, selezionare l'identità gestita assegnata dal sistema del tuo centro API che hai aggiunto nella sezione precedente. Fare clic su Seleziona.
   4. Seleziona Rivedi + assegna.

interfaccia della riga di comando di Azure

1. Ottenere l'ID principale dell'identità. Per un'identità assegnata dal sistema, usare il 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. Ottenere l'ID risorsa dell'insieme di credenziali delle chiavi usando il 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. Assegnare l'identità gestita al ruolo Utente dei segreti di Key Vault nell'insieme di credenziali delle chiavi al 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 
   

Integrare un repository Git

Per integrare un repository Git:

1. Nel portale di Azure passare al centro API.

2. Nel menu della barra laterale selezionare Piattaforme>Integrazioni.

3. Selezionare + Nuova integrazione e scegliere Da repository Git.

4. In Integrare il repository Git immettere le informazioni seguenti:

   Campo	Description
   Configurare l'origine del repository Git
   Repository URL	Immettere l'URL del repository Git contenente i file di asset. Se necessario, specificare il ramo e la sottocartella, ad esempio https://github.com/<org>/<repo>/tree/main/skills.
   Provider Git	Selezionare il provider , ad esempio GitHub.
   Configurazione del tipo di asset	Il Centro API configura un tipo di asset skill predefinito con lo schema **/skill.md di file. Selezionare + Aggiungi tipo di asset per aggiungere uno o più tipi di asset da sincronizzare.
   Token di accesso personale	Se si dispone di un PAT archiviato in Azure Key Vault, fare clic su Seleziona per sfogliare l'elemento segreto di Key Vault. Facoltativamente, selezionare Configura automaticamente l'identità gestita e assegna le autorizzazioni se non hai configurato manualmente un'identità gestita per accedere al segreto della chiave del vault.
   Dettagli di integrazione	Accettare l'identificatore del collegamento generato o specificare un ID personalizzato per il collegamento di integrazione.
   Dettagli ambiente
   Titolo ambiente	Immettere un nome descrittivo per l'ambiente del repository, ad esempio il repository Git.
   Identificazione	Immettere un nome di risorsa dell'ambiente, ad esempio git-repository.
   Tipo di ambiente	Selezionare il tipo di ambiente , ad esempio Produzione.
   Descrizione	Facoltativamente, aggiungere una descrizione per l'ambiente.
   Dettagli dell'asset
   Ciclo di vita	Selezionare la fase del ciclo di vita per gli asset sincronizzati dal repository , ad esempio Progettazione.

   

5. Fare clic su Crea.

Il portale aggiunge l'ambiente al centro API. Il portale aggiunge le risorse dal repository all'inventario del centro API nella pagina Inventario>Risorse. È possibile identificare gli asset collegati tramite l'icona di collegamento nell'elenco.

Contenuti correlati

• Registrare e individuare le competenze nell'inventario DELLE API
• Concetti chiave nel Centro API di Azure