Esercitazione: Pubblicare più versioni dell'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

Version shown in Azure portal

Prerequisiti

Aggiungere una nuova versione

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

API context menu - add version

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.

Add version window

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.

Versions listed under an API in the Azure portal

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:

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

Add version to product

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:

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, quindi Demo Conference API (API Demo Conference).
  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:

  • 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: