Usare l'interfaccia della riga di comando di Azure per gestire l'inventario delle API

Questo articolo illustra come usare i comandi az apic api nell'interfaccia della riga di comando di Azure per aggiungere e configurare API nell’inventario del centro API. Usare i comandi nell'interfaccia della riga di comando di Azure per creare script per gestire l'inventario delle API e altri aspetti del centro API.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il 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 informazioni sulle modifiche e sugli aggiornamenti più recenti in apic-extension.

Registrare l'API, la versione dell'API e la definizione

I passaggi seguenti illustrano come creare un'API e associare una singola versione dell'API e una definizione API. Per informazioni generali sul modello di dati nel Centro API di Azure, vedere Concetti chiave.

Creare un'API

Usare il comando az apic api create per creare un'API nel centro API.

L'esempio seguente crea un'API denominata API Petstore nel gruppo di risorse myResourceGroup e nel centro API myAPICenter. L'API è un'API REST.

az apic api create  --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

Creare una versione dell'API

Usare il comando az apic api version create per creare una versione per l'API.

L'esempio seguente crea una versione API denominata v1-0-0 per l'API petstore-api creata nella sezione precedente. La versione è impostata sulla fase test del ciclo di vita.

az apic api version create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

Creare la definizione dell'API e aggiungere un file di specifica

Usare i comandi az apic api definition per aggiungere una definizione e un file di specifica a corredo per una versione dell'API.

Creare una definizione

L'esempio seguente usa il comando az apic api definition create per creare una definizione denominata openapi per la versione dell'API petstore-api creata nella sezione precedente.

az apic api definition create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

Importare un file di specifica

Importare un file di specifica nella definizione usando il comando az apic api definition import-specification.

Nell'esempio seguente viene importato un file di specifica OpenAPI da un URL accessibile pubblicamente alla definizione openapi creata nel passaggio precedente. Le proprietà name e version della risorsa di specifica vengono passate come JSON.

az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

Esportare un file di specifica

Per esportare una specifica API dal centro API in un file locale, usare il comando az apic api definition export-specification.

Nell'esempio seguente il file di specifica viene esportato dalla definizione openapi creata nella sezione precedente in un file locale denominato specificationFile.json.

az apic api definition export-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

Registrare l'API da un file di specifica - singolo passaggio

È possibile registrare un'API da un file di specifica locale in un singolo passaggio usando il comando az apic api register. Con questa opzione, viene creata automaticamente una versione e una definizione dell'API predefinita per l'API.

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

az apic api register --resource-group myResourceGroup \
    --service-name myAPICenter --api-location "/Path/to/specificationFile.json"

• Il comando imposta le proprietà dell'API, ad esempio nome e tipo, dai valori nel file di definizione.
• Per impostazione predefinita, il comando imposta la fase ciclo di vita dell'API su progettare.
• Crea una versione dell'API denominata in base alla proprietà version nella definizione dell'API (o 1-0-0 per impostazione predefinita) e una definizione API denominata in base al formato di specifica (ad esempio, openapi).

Aggiornare le proprietà dell'API

Dopo aver registrato un'API, è possibile aggiornare le proprietà dell'API usando i comandi az apic api update, az apic api version update e az apic api definition update.

L'esempio seguente aggiorna il titolo dell'API petstore-api all'API Petstore v2.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API v2"

L'esempio seguente imposta la proprietà personalizzata interna booleana dell'API su false.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --set custom_properties.internal=false

Eliminare le risorse dell'API

Usare il comando az apic api delete per eliminare un'API e tutte le relative risorse di versione e definizione. Ad esempio:

az apic api delete \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api

Per eliminare singole versioni e definizioni dell'API, usare, rispettivamente, az apic api version delete e az apic api definition delete.

Contenuto correlato

• Vedere le Informazioni di riferimento sull'interfaccia della riga di comando di Azure per il Centro API di Azure per un elenco di comandi completo, inclusi i comandi per gestire gli ambienti, le distribuzioni, gli schemi di metadati e i servizi.
• Importare le API nel centro API da Gestione API
• Usare l'estensione di Visual Studio per il Centro API per compilare e registrare API da Visual Studio Code.
• Registrare le API nel centro API usando GitHub Actions