Versioni in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

Le versioni consentono di presentare agli sviluppatori gruppi di API correlate. È possibile usare le versioni per gestire in modo sicuro le modifiche di rilievo nelle API. I client possono scegliere di usare la nuova versione dell'API quando sono pronti, mentre i client esistenti continuano a usare una versione precedente. Le versioni vengono differenziate tramite un identificatore di versione (che è un valore stringa a scelta) e uno schema di controllo delle versioni permette ai client di identificare la versione di un'API da usare.

Nella maggior parte dei casi, ogni versione dell'API può essere considerata un'API indipendente. Due diverse versioni dell'API possono avere diversi set di operazioni e criteri diversi.

Con le versioni è possibile:

• Pubblicare più versioni dell'API contemporaneamente.
• Usare un percorso, una stringa di query o un'intestazione per distinguere le versioni.
• Usare qualsiasi valore stringa con cui si desidera identificare la versione, che può essere un numero, una data o un nome.
• Visualizzare le versioni dell'API raggruppate nel portale per sviluppatori.
• Accettare un'API esistente (non con versione) e crearne una nuova senza interrompere i client esistenti.

Per iniziare a usare le versioni, seguire la procedura dettagliata.

Schemi di controllo delle versioni

Diversi sviluppatori di API hanno requisiti diversi per il controllo delle versioni. Gestione API di Azure non prevede un unico approccio al controllo delle versioni, ma offre invece diverse opzioni.

Controllo delle versioni basato sul percorso

Quando viene usato lo schema di controllo delle versioni del percorso, l'identificatore della versione deve essere incluso nel percorso URL per tutte le richieste API.

Ad esempio, https://apis.contoso.com/products/v1 e https://apis.contoso.com/products/v2 possono fare riferimento alla stessa API products, ma alle versioni v1 e v2 rispettivamente.

Il formato di un URL di richiesta API quando si usa il controllo delle versioni basato sul percorso è: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Controllo delle versioni basato su intestazione

Quando viene usato lo schema di controllo delle versioni dell'intestazione, l'identificatore della versione deve essere incluso in un'intestazione di richiesta HTTP per tutte le richieste API. È possibile specificare il nome dell'intestazione della richiesta HTTP.

Ad esempio, è possibile creare un'intestazione personalizzata denominata Api-Versione i client potrebbero specificare v1 o v2 nel valore di questa intestazione.

Controllo delle versioni basato su stringhe di query

Quando viene usato lo schema di controllo delle versioni delle stringhe di query, l'identificatore della versione deve essere incluso in un parametro della stringa di query per le richieste API. È possibile specificare il nome del parametro della stringa di query.

Il formato di un URL di richiesta API quando si usa il controllo delle versioni basato su stringhe di query è: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Ad esempio, https://apis.contoso.com/products?api-version=v1 e https://apis.contoso.com/products?api-version=v2 possono fare riferimento alla stessa API products, ma alle versioni v1 e v2 rispettivamente.

Nota

I parametri di query non sono consentiti nella proprietà servers di una specifica OpenAPI. Se si esporta una specifica OpenAPI da una versione dell'API, non verrà visualizzata una stringa di query nell'URL del server.

Versioni originali

Se si aggiunge una versione a un'API senza controllo delle versioni, verrà creata automaticamente una versione Original e risponderà sull'URL predefinito, senza un identificatore di versione specificato. La versione Original garantisce che tutti i chiamanti esistenti non vengano interrotti dal processo di aggiunta di una versione. Se si crea una nuova API con le versioni abilitate sin dall'inizio, non viene creata una versione Original.

Come vengono rappresentate le versioni

Gestione API di Azure gestisce una risorsa denominata set di versioni, che rappresenta un set di versioni per una singola API logica. Un set di versioni contiene il nome visualizzato dell'API con versione e lo schema di controllo delle versioni usato per indirizzare le richieste alle versioni specificate.

Ogni versione di un'API viene mantenuta come propria risorsa API, che viene quindi associata a un set di versioni. Un set di versioni può contenere API con operazioni o criteri diversi. È possibile apportare modifiche significative tra le versioni di un set.

Il portale di Azure crea automaticamente i set di versioni. È possibile modificare il nome e la descrizione per un set di versioni nel portale di Azure.

Un set di versioni viene eliminato automaticamente quando viene eliminata la versione finale.

È possibile visualizzare e gestire i set di versioni direttamente usando l'interfaccia della riga di comando di Azure, Azure PowerShell, modelli di Resource Manager o l'API di Azure Resource Manager.

Nota

Tutte le versioni di un set di versioni hanno lo stesso schema di controllo delle versioni, in base allo schema di controllo delle versioni usato per la prima volta quando si aggiunge una versione a un'API.

Migrazione di un'API senza controllo delle versioni a un'API con controllo delle versioni

Quando si usa il portale di Azure per abilitare il controllo delle versioni in un'API esistente, vengono apportate le modifiche seguenti alle risorse di Gestione API:

• Viene creato un nuovo set di versioni.
• La versione esistente viene mantenuta e configurata come versione dell'API Original. L'API è collegata al set di versioni, ma non richiede che venga specificato un identificatore di versione.
• La nuova versione viene creata come nuova API ed è collegata al set di versioni. È necessario accedere a questa nuova API usando lo schema di controllo delle versioni e l'identificatore.

Versioni e revisioni

Le versioni e le revisioni sono caratteristiche distinte. Ogni versione può avere più revisioni, proprio come un'API senza controllo delle versioni. È possibile usare le revisioni senza usare le versioni o in altro modo. In genere le versioni vengono usate per separare le versioni delle API con modifiche di rilievo, mentre le revisioni possono essere usate per delle modifiche secondarie e non di rilievo a un'API.

Se si ritiene che la revisione abbia delle modifiche di rilievo o se si desidera trasformare formalmente la revisione in una versione beta/test, è possibile creare una versione da una revisione. Usando il portale di Azure, fare clic su "Crea versione da revisione" nel menu di scelta rapida della revisione nella scheda Revisioni.

Portale per sviluppatori

Il portale per sviluppatori elenca ogni versione di un'API separatamente.

I dettagli di un'API mostrano anche un elenco di tutte le versioni di tale API. Viene visualizzata una versione Original senza un identificatore di versione.

Suggerimento

Le versioni API devono essere aggiunte a un prodotto prima che siano visibili nel portale per sviluppatori.