Sincronizzare le API da un'istanza di Gestione API

Questo articolo illustra come integrare un'istanza di Gestione API in modo che le API delle istanze siano costantemente aggiornate nell'inventario del centro API .

Tip

Questo articolo illustra come integrare un'istanza di Gestione API dal centro API. In alternativa, configurare rapidamente l'integrazione direttamente da un'istanza di Gestione API. Nel menu a sinistra dell'istanza, in API selezionare Centro API e selezionare un centro API di destinazione nella sottoscrizione per sincronizzare le API.

Informazioni sull'integrazione di un'istanza di Gestione API

Sebbene sia possibile usare l'interfaccia della riga di comando di Azure per importare API su richiesta da Gestione API di Azure al Centro API di Azure, l'integrazione (collegamento) di un'istanza di Gestione API consente la sincronizzazione continua in modo che l'inventario API rimanga aggiornato. Il Centro API di Azure può anche sincronizzare le API da origini, tra cui Amazon API Gateway.

Quando si integra un'istanza di Gestione API come origine API, si verifica quanto segue:

1. Tutte le API e, facoltativamente, le definizioni API (specifiche), dall'istanza di Gestione API vengono aggiunte all'inventario del centro API. I server MCP in Gestione API sono inclusi nelle API aggiunte all'inventario.
2. Configurare un ambiente di tipo Gestione API di Azure nel centro API.
3. Viene creata una distribuzione associata per ogni definizione dell'API sincronizzata da Gestione API.

Le API di Gestione API vengono sincronizzate automaticamente con il centro API ogni volta che le impostazioni delle API esistenti cambiano (ad esempio, vengono aggiunte nuove versioni), vengono create nuove API o vengono eliminate le API. Questa sincronizzazione è unidirezionale da Gestione API al centro API di Azure, ovvero gli aggiornamenti API nel centro API non vengono sincronizzati con l'istanza di Gestione API.

Note

• Esistono limiti per il numero di istanze integrate di Gestione API (origini API).
• Un'istanza integrata di Gestione API può essere configurata in una rete virtuale.
• Gli aggiornamenti API in Gestione API in genere si sincronizzano con il centro API entro pochi minuti, ma la sincronizzazione può richiedere fino a 24 ore.
• Le definizioni API vengono sincronizzate anche con il centro API se si seleziona l'opzione per includerle durante l'integrazione.

Entità sincronizzate da Gestione API

È possibile aggiungere o aggiornare le proprietà e la documentazione dei metadati alle API sincronizzate nel centro API per aiutare gli stakeholder a individuare, comprendere e usare le API. Altre informazioni sulle proprietà predefinite e personalizzate dei metadati del Centro API di Azure.

La tabella seguente illustra le proprietà dell'entità che possono essere modificate nel Centro API di Azure e le proprietà impostate in base ai relativi valori nell'origine API.

Entity	Proprietà configurabili nel Centro API	Proprietà determinate nell'origine API integrata
API	summary lifecycleStage termsOfService license externalDocumentation customProperties	title description kind
Versione dell'API	lifecycleStage	title definizioni (se sincronizzate)
Environment	title description tipo server.managementPortalUri onboarding customProperties	server.type
Deployment	title description server state customProperties	server.runtimeUri

Note

Gli ID risorsa e di sistema per le entità sincronizzate nel Centro API di Azure vengono generati automaticamente e non possono essere modificati.

Prerequisites

• Un centro API nella sottoscrizione di Azure. Se non ne è stato creato uno, vedere Guida introduttiva: Creare il centro API.

• Istanza di Gestione API di Azure, nella stessa sottoscrizione o in una sottoscrizione diversa. L'istanza deve trovarsi nella stessa directory.

• Per l'interfaccia della riga di comando di Azure:

  • Utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

    

  • Se preferisci eseguire localmente i comandi di riferimento della CLI, installa l'Azure CLI. Per l'esecuzione in Windows o macOS, considerare l'esecuzione dell'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l’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 richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'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

  I comandi az apic richiedono l'estensione dell'interfaccia della riga di comando di Azure apic-extension. Se non sono stati usati comandi az apic, l'estensione può essere installata in modo dinamico quando si esegue il primo comando az apic oppure è possibile installarla manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.

  Vedere le note sulla versione per le modifiche e gli aggiornamenti più recenti in apic-extension. Alcune funzionalità possono richiedere un'anteprima o una versione specifica dell'estensione.

  Note

  Gli esempi di comandi dell'interfaccia della riga di comando di Azure riportati in questo articolo possono essere eseguiti 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.

Abilitare un'identità gestita nel centro API

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, passare al centro API.
2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.
3. Selezionare Sistema assegnato e impostare lo stato su Sì.
4. Seleziona Salva.

CLI 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 lettore del servizio Gestione API

Per consentire l'importazione delle API, assegnare all'identità gestita del centro API il ruolo Lettore del servizio Gestione API nell'istanza di Gestione API. È possibile usare il portale o l'interfaccia della riga di comando di Azure.

Portal

1. Nel portale, andare all'istanza di API Management.
2. Nel menu a sinistra 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 Ruolo, selezionare Lettore del servizio Gestione API.
   2. Nella scheda Membri, in Assegnare l'accesso a - Selezionare Identitàgestita>+ Seleziona membri.
   3. Nella pagina Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema del centro API aggiunto nella sezione precedente. Fare clic su Seleziona.
   4. Selezionare Rivedi e assegna.

CLI di Azure

1. Ottenere l'ID entità di sicurezza 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'istanza di Gestione API usando il 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. Assegnare l'identità gestita al ruolo Lettore del servizio Gestione API nell'istanza di Gestione API usando il 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 
   

Integrare un'istanza di Gestione API

È possibile integrare un'istanza di Gestione API usando il portale o l'interfaccia della riga di comando di Azure.

Portal

1. Nel portale, passare al centro API.
2. In Piattaforme selezionare Integrazioni.
3. Selezionare + Nuova integrazione>da Gestione API di Azure.
4. Nella pagina Integrare il servizio Gestione API di Azure :
   1. Selezionare se sincronizzare tutte le API dall'istanza di Gestione API o solo le API presenti in un'area di lavoro Gestione API.
   2. Selezionare la sottoscrizione, il gruppo di risorse e il servizio Gestione API di Azure che si vuole integrare. Se si desidera sincronizzare solo le API da un'area di lavoro, effettuare una selezione in Scegliere un'area di lavoro.
   3. In Dettagli integrazione immettere un identificatore. Se non è già stata configurata un'identità gestita con accesso all'istanza di Gestione API, abilitare Configura automaticamente l'identità gestita e assegna le autorizzazioni. Questa selezione assegna automaticamente all'identità gestita assegnata dal sistema del centro API le autorizzazioni necessarie per sincronizzare le API dall'istanza di Gestione API.
   4. In Dettagli ambiente immettere un titolo ambiente (nome), tipo di ambiente e Descrizione facoltativa.
   5. In Dettagli API:
      1. Selezionare un ciclo di vita per le API sincronizzate. (È possibile aggiornare questo valore per le API dopo l'aggiunta al centro API).
      2. Facoltativamente, selezionare se includere definizioni API con le API sincronizzate.
5. Fare clic su Crea.

CLI di Azure

Eseguire il comando az apic integration create apim per integrare un'istanza di Gestione API nel centro API.

• Specificare i nomi del gruppo di risorse, del centro API e dell'integrazione.

• Se l'istanza di Gestione API e il centro API si trovano nello stesso gruppo di risorse, è possibile specificare il nome dell'istanza di Gestione API come valore di azure-apim; in caso contrario, specificare l'ID della risorsa di Azure.

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>

L'istanza di Gestione API è integrata come ambiente nel centro API. Le API di Gestione API vengono sincronizzate con l'inventario del centro API.

Eliminare un'integrazione

Mentre un'origine API è integrata, non è possibile eliminare le API sincronizzate dal centro API. Se necessario, è possibile eliminare l'integrazione. Quando si elimina un'integrazione:

• Le API sincronizzate nell'inventario del centro API vengono eliminate
• L'ambiente e le distribuzioni associate all'origine API vengono eliminate

È possibile eliminare un'integrazione usando il portale o l'interfaccia della riga di comando di Azure.

Portal

1. Nel portale, passare al centro API.
2. In Asset, selezionare Ambienti>Integrazioni (anteprima).
3. Selezionare l'integrazione e quindi elimina (icona del cestino).

CLI di Azure

Eseguire il comando az apic integration delete (anteprima) per eliminare un'integrazione. Specificare i nomi del gruppo di risorse, del centro API e dell'integrazione.

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

Contenuti correlati

• Gestire l'inventario API con i comandi dell'interfaccia della riga di comando di Azure
• Importare API da Gestione API al centro API di Azure
• Registrare e individuare i server MCP nel centro API
• Documentazione di Gestione API di Azure