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 le API nell'inventario del Centro API di Azure . 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 Introduzione ad 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 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.
  - 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.

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"}'

Suggerimento

È possibile importare il file di specifica inline impostando il parametro --format su inline e passando il contenuto del file usando il parametro --value.

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

Usando il comando az apic api register , è possibile registrare un'API da un file di specifica locale in un unico passaggio. 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 booleana internal 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.

Vedere le informazioni di riferimento per i comandi del Centro API di Azure, inclusi i comandi per gestire ambienti, distribuzioni, schemi di metadati e servizi.
Importare le API nel centro API da Gestione API
Compilare e registrare API con l'estensione Centro API di Azure per Visual Studio Code
Registrare le API nel centro API usando GitHub Actions

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-09