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 specificare più versioni in Gestione API di Azure.
Per i concetti di base, vedere Versioni e revisioni.
In questa esercitazione apprenderai a:
- Aggiungere una nuova versione a un'API esistente
- Scegliere uno schema di versione
- Aggiungere la versione a un prodotto
- Passare al portale per sviluppatori per visualizzare la versione
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
- Nel portale di Azure accedere all'istanza di Gestione API.
- Selezionare API.
- Selezionare Demo Conference API (API Demo Conference) nell'elenco di API.
- Selezionare il menu di scelta rapida (...) accanto a Demo Conference API.
- Selezionare Aggiungi versione.
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 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.
| Impostazione | valore | Descrizione |
|---|---|---|
| Nome | demo-conference-api-v1 | Nome univoco nell'istanza di Gestione API. Poiché una versione è in realtà una nuova API basata sulla revisione di un'API, questa impostazione è il nome della nuova API. |
| Schema di controllo delle versioni | Percorso | Modo in cui i chiamanti specificano la versione dell'API. |
| Identificatore di versione | v1 | Indicatore della versione specifico dello schema. Per Percorso, il suffisso per il percorso dell'URL dell'API. Se si seleziona Intestazione o Stringa di query come schema di controllo delle versioni, è necessario immettere un valore aggiuntivo, ovvero il nome dell'intestazione o il parametro della stringa di query. Viene visualizzato un esempio di utilizzo. |
| Prodotti | Illimitato | 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. |
Una volta creata, la versione viene visualizzata sotto Demo Conference API nell'elenco di API. Vengono ora visualizzate due API: Originale v1.
Nota
Se si aggiunge una versione a un'API senza controllo delle versioni, viene automaticamente creata una versione Originale, che risponde dall'URL predefinito. La creazione di una versione originale garantisce che i chiamanti esistenti non subiscano interruzioni a causa della procedura di aggiunta della versione. Se si crea una nuova API con le versioni abilitate sin dall'inizio, non viene creata alcuna versione originale.
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 sulle altre. 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:
- Nel portale di Azure accedere all'istanza di Gestione API.
- Selezionare Prodotti>Illimitato>API>+ Aggiungi.
- Selezionare Demo Conference API versione v1.
- 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 la Avvio rapido di 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.
- Selezionare Portale per sviluppatori dal menu principale.
- Selezionare API, quindi Demo Conference API (API Demo Conference).
- Verrà visualizzato un elenco a discesa con 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.
Passaggi successivi
Questa esercitazione ha descritto come:
- Aggiungere una nuova versione a un'API esistente
- Scegliere uno schema di versione
- Aggiungere la versione a un prodotto
- Passare al portale per sviluppatori per visualizzare la versione
Passare all'esercitazione successiva: