Sincronizzare le API da un'istanza di Gestione API (anteprima)

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.

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 Azure Gestione API al Centro API di Azure, l'integrazione (collegamento) di un'istanza di Gestione API abilita 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.
2. Configurare un ambiente di tipo Azure Gestione API nel centro API.
3. Viene creata una distribuzione associata per ogni definizione dell'API sincronizzata da Gestione API.

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

Nota

• L'integrazione di Azure Gestione API è attualmente in anteprima.
• Esistono limiti per il numero di istanze di Gestione API integrate (origini API).
• Gli aggiornamenti delle 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.

Entità	Proprietà configurabili nel Centro API	Proprietà determinate nell'origine API integrata
API	riepilogo lifecycleStage termsOfService Licenza externalDocumentation customProperties	title description kind
Versione dell'API	lifecycleStage	title definizioni (se sincronizzate)
Ambiente	title description kind server.managementPortalUri onboarding customProperties	server.type
Distribuzione	title description server state customProperties	server.runtimeUri

Nota

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

Prerequisiti

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

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

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

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'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 si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite 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 le estensioni con l'interfaccia della riga di comando di Azure.

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

  Nota

  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.

  Nota

  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.

Portale

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.

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

Portale

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 Gestione API Lettore di servizi.
   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. Seleziona Rivedi + assegna.

Interfaccia della riga di comando di Azure

1. Ottenere l'ID entità 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.

Portale

1. Nel portale, passare al centro API.
2. In Asset selezionare Ambienti.
3. Selezionare Collegamenti (anteprima)>+ Crea un collegamento.
4. Nella pagina Collegare il servizio azure Gestione API:
   1. Selezionare il servizio Sottoscrizione, Gruppo di risorse e Azure Gestione API che si vuole integrare.
   2. In Dettagli collegamento immettere un identificatore.
   3. In Dettagli ambiente immettere un titolo ambiente (nome), tipo di ambiente e Descrizione facoltativa.
   4. 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. Selezionare Crea.

Interfaccia della riga di comando 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 Gestione API come valore di azure-apim; in caso contrario, specificare l'ID 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'ambiente viene aggiunto nel centro API. Le API Gestione API vengono importate nell'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.

Portale

1. Nel portale, passare al centro API.
2. In Asset selezionare Collegamenti ambienti>(anteprima).
3. Selezionare il collegamento e quindi selezionare Elimina (icona del cestino).

Interfaccia della riga di comando 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> \

Contenuto correlato

• 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
• Documentazione di Gestione API di Azure