Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
SI APPLICA A: Tutti i livelli di Gestione API
In alcune situazioni è poco pratico che tutti i consumer di API usino la stessa versione. Quando i consumer sono pronti per eseguire l'aggiornamento a una versione più recente, preferiscono un approccio semplice e comprensibile. Come illustrato in questa esercitazione, Gestione API di Azure supporta l'esposizione di più versioni dell'API per soddisfare questa esigenza.
Per i concetti di base, vedere Versioni e Revisioni.
Suggerimento
I team API possono usare questa funzionalità nelle aree di lavoro. Le aree di lavoro forniscono accesso amministrativo isolato alle API e ai propri ambienti di runtime API.
In questa esercitazione apprenderai a:
- Aggiungere una nuova versione a un'API esistente
- Scegliere uno schema di versione
- Aggiungere la versione a un prodotto
- Visualizzare la versione nel portale per sviluppatori
Prerequisiti
- Informazioni sulla terminologia di Gestione API di Azure.
- Completare la procedura rapida Creare un'istanza di Gestione API di Azure.
- Completare l'esercitazione Importare e pubblicare la prima API.
Aggiungere una nuova versione
- Nel portale di Azure accedere all'istanza di Gestione API.
- Nel menu a sinistra, nella sezione API selezionare API.
- Individuare Swagger Petstore - OpenAPI 3.0 nell'elenco delle API. Selezionare i puntini di sospensione (...) accanto a Swagger Petstore - OpenAPI 3.0 e quindi selezionare Aggiungi versione. Nella sezione successiva verranno aggiunti valori alla finestra risultante.
Suggerimento
È anche possibile abilitare le versioni quando si crea una nuova API. Nella schermata Aggiungi API selezionare Assegnare un numero di versione a questa API?.
Scegliere uno schema di controllo delle versioni
In Gestione API scegliere il modo in cui i chiamanti specificano la versione dell'API selezionando uno schema di controllo delle versioni: Percorso, Intestazione o Stringa di query. Nell'esempio seguente, Path viene usato come schema di controllo delle versioni.
Nella finestra Crea una nuova API come versione immettere i valori della tabella seguente. Fare quindi clic su Crea per creare la versione.
| Impostazione | valore | Descrizione |
|---|---|---|
| Identificatore di versione | v1 | Indicatore della versione specifico dello schema. Per Percorso, il suffisso per il percorso dell'URL dell'API. |
| Schema di controllo delle versioni | Percorso | Modo in cui i chiamanti specificano la versione dell'API. Se si seleziona Intestazione o Stringa di query, immettere un altro valore: il nome del parametro dell'intestazione o della stringa di query. Viene visualizzato un esempio di utilizzo. |
| Nome completo della versione dell'API | swagger-petstore-openapi-3-0-v1 | Nome univoco nell'istanza di Gestione API. Poiché una versione è in realtà una nuova API basata sulla revisione di un'API, questo valore è il nome della nuova API. |
| Prodotti | Illimitato (fornito in alcuni livelli di servizio) | Facoltativamente, uno o più prodotti a cui è associata la versione dell'API. Per pubblicare l'API, è necessario associarla a un prodotto. È anche possibile aggiungere la versione a un prodotto in un secondo momento. |
Dopo aver creato la versione, viene visualizzata in Swagger Petstore - OpenAPI 3.0 nell'elenco api. Vengono ora visualizzate due API: Original e v1:
Nota
Se si aggiunge una versione a un'API senza controllo delle versioni, viene creata automaticamente anche una versione originale. che risponde dall'URL predefinito. La versione originale assicura che le chiamate dai chiamanti esistenti funzionino ancora dopo l'aggiunta della versione. Se si crea una nuova API con versioni abilitate all'inizio, non viene creato un originale.
Modificare una versione
Dopo aver aggiunto la versione, è possibile modificarla e configurarla come API separata dall'originale. Le modifiche apportate a una versione non influiscono su un'altra (ad esempio, se si aggiungono o si rimuovono operazioni API o si modifica la specifica OpenAPI). Per altre informazioni, vedere Modificare un'API.
Aggiungere la versione a un prodotto
Per consentire ai chiamanti di visualizzare la nuova versione, è necessario aggiungerla a un prodotto. Se non è già stata aggiunta la versione a un prodotto, è possibile farlo in qualsiasi momento.
Per aggiungere la versione a un prodotto:
- Nel portale di Azure accedere all'istanza di Gestione API.
- In API nel riquadro sinistro selezionare Prodotti.
- Selezionare il prodotto e quindi selezionare API nel riquadro sinistro.
- Seleziona + Aggiungi.
- Selezionare l'API.
- 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. Se si seleziona il nome di un'API con più versioni, il portale visualizza il set di versioni. È possibile personalizzare il nome e la descrizione di un set di versioni.
È 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 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.
Per visualizzare tutti i set di versioni, eseguire il comando az apim api versionset list:
az apim api versionset list --resource-group <resource-group-name> \
--service-name <API-Management-service-name> --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 <resource-group-name> \
--service-name <API-Management-service-name> --version-set-id <ID from the Name column>
Per altre informazioni sui set di versioni, vedere Versioni in Gestione API di Azure.
Visualizzare la versione nel portale per sviluppatori
Se si usa il portale per sviluppatori, è possibile visualizzare le versioni dell'API.
- Selezionare Portale per sviluppatori nella parte superiore della finestra.
- Selezionare API e quindi Swagger Petstore.
- Verrà visualizzato un elenco a discesa che elenca più versioni accanto al nome dell'API.
- Selezionare v1.
- Si noti l'URL della richiesta della prima operazione nell'elenco. Mostra che il percorso dell'URL dell'API include v1.
Passo successivo
Passare all'esercitazione successiva: