Importare le API nel centro API da Gestione API di Azure

Questo articolo illustra come importare (aggiungere) API da un'istanza di Gestione API di Azure al centro API usando l'interfaccia della riga di comando di Azure. L'aggiunta di API da Gestione API all'inventario API consente di renderle individuabili e accessibili agli sviluppatori, ai responsabili dei programmi API e ad altri stakeholder dell'organizzazione.

Questo articolo illustra due opzioni per l'uso dell'interfaccia della riga di comando di Azure per aggiungere API al centro API da Gestione API:

• Opzione 1: esportare una definizione API da un'istanza di Gestione API usando il comando az apim api export. Importare quindi la definizione nel centro API.

  I modi possibili per importare una definizione API esportata da Gestione API includono:

  • Eseguire az apic api register per registrare una nuova API nel centro API.
  • Eseguire az apic api definition import-specification per importare la definizione dell'API in un'API esistente.

• Opzione 2: importare LE API direttamente da Gestione API al centro API usando il comando az apic import-from-apim.

Dopo aver importato definizioni API o API da Gestione API, è possibile aggiungere metadati e documentazione nel centro API per aiutare gli stakeholder a individuare, comprendere e usare l'API.

Prerequisiti

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

• Una o più istanze di Gestione API di Azure, nella stessa sottoscrizione o in una sottoscrizione diversa. Quando si importano API direttamente da Gestione API, l'istanza di Gestione API e il centro API devono trovarsi nella stessa directory. Se non ne è stato creato uno, vedere Creare un'istanza di Gestione API di Azure.

• Una o più API gestite nell'istanza di Gestione API da aggiungere al centro API.

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

  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.

Opzione 1: esportare una definizione API da Gestione API e importarla nel centro API

Prima di tutto, esportare un'API dall'istanza di Gestione API in una definizione API usando il comando az apim api export . A seconda dello scenario, è possibile esportare la definizione dell'API in un file locale o in un URL.

Esportare l'API in un file di definizione dell'API locale

Il comando di esempio seguente esporta l'API con identificatore my-api nell'istanza myAPIManagement dell'API . L'API viene esportata in formato OpenApiJson in un file di definizione OpenAPI locale nel percorso specificato.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Esportare l'API in un URL

Nell'esempio seguente az apim api export esporta l'API con identificatore my-api in formato OpenApiJson in un URL in Archiviazione di Azure. L'URL è disponibile per circa 5 minuti. In questo caso, il valore dell'URL viene archiviato nella variabile $link .

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Registrare l'API nel centro API dalla definizione dell'API esportata

È possibile registrare una nuova API nel centro API dalla definizione esportata usando il comando az apic api register .

L'esempio seguente registra un'API nel centro API myAPICenter da un file di definizione OpenAPI locale denominato definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Importare la definizione dell'API in un'API esistente nel centro API

L'esempio seguente usa il comando az apic api definition import-specification per importare una definizione API in un'API esistente nel centro API myAPICenter. In questo caso, la definizione dell'API viene importata da un URL archiviato nella variabile $link .

Questo esempio presuppone che l'API sia denominata my-api e una versione API 1-0-0 associata e l'entità di definizione openapi nel centro API. In caso contrario, vedere Aggiungere API al centro API.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Opzione 2: importare API direttamente dall'istanza di Gestione API

Di seguito sono riportati i passaggi per importare le API dall'istanza di Gestione API al centro API usando il comando az apic import-from-apim . Questo comando è utile quando si vogliono importare più API da Gestione API al centro API, ma è anche possibile usarlo per importare una singola API.

Quando si aggiungono API da un'istanza di Gestione API al centro API usando az apic import-from-apim, si verifica automaticamente quanto segue:

• Le versioni,le definizioni ele informazioni sulla distribuzione di ogni API vengono copiate nel centro API.
• L'API riceve un nome API generato dal sistema nel centro API. Mantiene il nome visualizzato (titolo) da Gestione API.
• La fase del ciclo di vita dell'API è impostata su Progettazione.
• Gestione API di Azure viene aggiunto come ambiente.

Aggiungere un'identità gestita nel centro API

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

Gli esempi seguenti illustrano come configurare 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.

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.

Importare API da Gestione API

Usare il comando az apic import-from-apim per importare una o più API dall'istanza di Gestione API al centro API.

Importare tutte le API da un'istanza di Gestione API

Nel comando seguente sostituire i nomi del centro API, il gruppo di risorse del centro API, l'istanza di Gestione API e il gruppo di risorse dell'istanza. Usare * per specificare tutte le API dall'istanza di Gestione API.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

Importare un'API specifica da un'istanza di Gestione API

Specificare un'API da importare usando il nome dell'istanza di Gestione API.

Nel comando seguente sostituire i nomi del centro API, il gruppo di risorse del centro API, l'istanza di Gestione API e il gruppo di risorse dell'istanza. Passare un nome API, ad esempio petstore-api, usando il parametro --apim-apis.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

Dopo aver importato LE API da Gestione API, è possibile visualizzare e gestire le API importate nel centro API.

Contenuto correlato

• Informazioni di riferimento dell'interfaccia della riga di comando di Azure per il Centro API di Azure
• Informazioni di riferimento dell'interfaccia della riga di comando di Azure per Gestione API
• Gestire l'inventario API con i comandi dell'interfaccia della riga di comando di Azure
• Assegnare ruoli di Azure a un'identità gestita
• Documentazione di Gestione API di Azure