Versioni in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

Le versioni consentono di presentare gruppi di API correlate agli sviluppatori. È 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 (ovvero qualsiasi valore stringa scelto) e uno schema di controllo delle versioni consente ai client di identificare la versione di un'API da usare. Questo articolo descrive come usare le versioni in Gestione API.

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.
• È possibile usare qualsiasi valore di stringa per identificare la propria versione. Può trattarsi di un numero, di una data o di un nome.
• Visualizzare le versioni dell'API raggruppate nel portale per sviluppatori.
• Creare una nuova versione di un'API esistente (non con controllo delle versioni) senza influire sui client esistenti.

Per iniziare a usare le versioni, completare una 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 può fare riferimento alla stessa products API, ma alle versioni v1 e v2a .

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

Versionamento basato su header HTTP

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 versionamento 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 può fare riferimento alla stessa products API, ma alle versioni v1 e v2a .

Annotazioni

I parametri di query non sono consentiti nella servers proprietà 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 Original versione e risponderà sull'URL predefinito, senza un identificatore di versione specificato. La Original versione garantisce che tutti i chiamanti esistenti non siano interessati dal processo di aggiunta di una versione. Se si crea una nuova API con versioni abilitate all'inizio, non viene creata una Original versione.

Come vengono rappresentate le versioni

Gestione API 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 ed è 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, i modelli di Resource Manager o l'API di Azure Resource Manager.

Annotazioni

Tutte le versioni di un set di versioni hanno lo stesso schema di controllo delle versioni. Si basa sullo 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'APIOriginal. L'API è collegata al set di versioni, ma non è necessario specificare un identificatore di versione.
• La nuova versione viene creata come nuova API ed è collegata al set di versioni. Per accedere alla nuova API, è necessario usare uno schema di controllo delle versioni e un 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 dell'API con modifiche di rilievo e le revisioni possono essere usate per modifiche secondarie e non di rilievo a un'API.

Se si ritiene che la revisione abbia modifiche di rilievo o se si desidera trasformare formalmente la revisione in una versione beta/test, è possibile creare una versione da una revisione. Nel portale di Azure selezionare Crea versione da questa revisione nel menu di scelta rapida revisione (...) nella scheda Revisioni .

Portale per sviluppatori

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

Nei dettagli di un'API è anche possibile visualizzare un elenco di tutte le versioni dell'API. Viene mostrata una versione senza identificazione di versione:

Suggerimento

È necessario aggiungere versioni API a un prodotto per renderle visibili nel portale per sviluppatori.