Esercitazione: Pubblicare più versioni dell'API

SI APPLICA A: Tutti i livelli di Gestione API

Talvolta, può risultare poco pratico che tutti i chiamanti dell'API usino esattamente la stessa versione. Quando i chiamanti sono pronti per passare a una versione successiva dell'API, preferiscono farlo adottando un approccio facile da comprendere. Come illustrato in questa esercitazione, è possibile fornire più versioni in Azure Gestione API.

Per i concetti di base, vedere Versioni e revisioni.

In questa esercitazione apprenderai a:

Prerequisiti

• Acquisire familiarità con la terminologia di Gestione API di Azure.
• Completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure.
• Completare anche l'esercitazione seguente: Importare e pubblicare la prima API.

Aggiungere una nuova versione

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. Selezionare API.
3. Selezionare Swagger Petstore nell'elenco api.
4. Selezionare il menu di scelta rapida (...) accanto a Swagger Petstore.
5. Selezionare Aggiungi versione.

Scegliere uno schema di controllo delle versioni

In Gestione API di Azure è possibile scegliere in che modo i chiamanti specificano la versione dell'API selezionando uno schema di controllo delle versioni: percorso, intestazione o stringa di query. L'esempio seguente mostra l'uso dello schema di controllo delle versioni di tipo percorso.

Immettere i valori dalla tabella seguente. Fare quindi clic su Crea per creare la versione.

Dopo aver creato la versione, viene ora visualizzata sotto Swagger Petstore nell'elenco api. Vengono ora visualizzate due API: Originale v1.

Modificare una versione

Dopo aver aggiunto la versione, è ora possibile modificarla e configurarla come API separata dall'API Original. Le modifiche apportate a una versione non influiscono su un'altra. Ad esempio, aggiungere o rimuovere operazioni API o modificare la specifica OpenAPI. Per altre informazioni, vedere Modificare un'API.

Aggiungere la versione a un prodotto

Perché i chiamanti possano visualizzare la nuova versione, questa deve essere aggiunta a un prodotto. Se ancora non è stata aggiunta la versione a un prodotto, è possibile aggiungerla in qualsiasi momento.

Ad esempio, per aggiungere la versione al prodotto Illimitato:

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. Selezionare Prodotti>Illimitato>API>+ Aggiungi.
3. Selezionare Swagger Petstore versione 1.
4. Fare clic su Seleziona.

Usare set di versioni

Quando si creano più versioni, il portale di Azure crea un set di versioni, che rappresenta un set di versioni per una singola API logica. Selezionare il nome di un'API con più versioni. Il portale di Azure visualizza il relativo set di versioni. È possibile personalizzare Nome e Descrizione di un set virtuale.

È possibile interagire direttamente con i set di versioni usando 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.

Per visualizzare tutti i set di versioni, eseguire il comando az apim api versionset list:

az apim api versionset list --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --output table

Quando il portale di Azure crea automaticamente un set di versioni, assegna un nome alfanumerico visualizzato nella colonna Nome dell'elenco. Usare questo nome in altri comandi dell'interfaccia della riga di comando di Azure.

Per visualizzare i dettagli su un set di versioni, eseguire il comando az apim api versionset show:

az apim api versionset show --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

Per altre informazioni sui set di versioni, vedere Versioni in Gestione API di Azure.

Passare al portale per sviluppatori per visualizzare la versione

Nel portale per sviluppatori è possibile visualizzare le versioni dell'API.

1. Selezionare Portale per sviluppatori dal menu principale.
2. Selezionare API e quindi Swagger Petstore.
3. Verrà visualizzato un elenco a discesa con più versioni accanto al nome dell'API.
4. Selezionare v1.
5. Si noti l'URL della richiesta della prima operazione nell'elenco. Mostra che il percorso dell'URL dell'API include v1.

Passaggi successivi

Questa esercitazione ha descritto come:

Passare all'esercitazione successiva: