Criteri di controllo delle versioni per servizi, SDK e strumenti dell'interfaccia della riga di comando di Azure

Articolo
12/13/2023

La maggior parte dei servizi di Azure consente di controllare e gestire le risorse a livello di codice con le API REST. I servizi si evolvono tramite nuove versioni pubblicate delle API con contratti diversi che aggiungono nuove funzionalità e/o modificano i loro comportamenti.

Questo articolo descrive i criteri usati dai team del servizio, dell'SDK e dell'interfaccia della riga di comando di Azure per il controllo delle versioni delle API REST di Azure. Mentre i team di Azure fanno ogni sforzo per rispettare questo criterio, le deviazioni possono verificarsi occasionalmente.

Controllo delle versioni dei servizi

Ogni versione pubblicata di un'API viene identificata da un valore di data nel YYYY-MM-DD formato , denominato api-version. Le versioni più recenti hanno date successive.

Tutte le operazioni API richiedono ai client di specificare una versione API valida per il servizio tramite il api-version parametro della stringa di query nell'URL. Ad esempio: https://management.azure.com/subscriptions?api-version=2020-01-01. Gli SDK e gli strumenti client includono automaticamente il api-version valore . Per altre considerazioni, vedere la sezione SDK client e versioni del servizio più avanti in questo articolo.

In genere, le versioni del servizio pubblicate rimangono disponibili e supportate per molti anni, anche quando diventano disponibili versioni più recenti. Nella maggior parte dei casi, l'unica volta che è necessario adottare una nuova versione del servizio all'interno del codice esistente consiste nell'sfruttare le nuove funzionalità.

Versioni stabili

La maggior parte delle versioni del servizio pubblicate sono versioni stabili. Le versioni stabili sono compatibili con le versioni precedenti, ovvero qualsiasi codice scritto che si basa su una versione di un servizio può adottare una versione stabile più recente senza richiedere modifiche al codice per mantenere la correttezza o le funzionalità esistenti.

Modifiche di rilievo

Una versione di modifica che causa un'interruzione di un servizio non è compatibile con le versioni precedenti. L'adozione di una versione di modifica che causa un'interruzione nel codice client esistente può richiedere modifiche al codice per garantire che il client si comporti esattamente come in caso di destinazione della versione precedente.

Le versioni delle modifiche di rilievo sono rare, annunciate tramite la documentazione e in genere sono precedute dalla pubblicazione di una versione di anteprima. La pubblicazione di una versione di modifica che causa un'interruzione può richiedere il ritiro finale delle versioni stabili esistenti, che rimarranno disponibili per almeno tre anni dopo le versioni di modifica di rilievo. Per le modifiche di rilievo pubblicate a causa di problemi di sicurezza o conformità, le versioni del servizio stabili esistenti possono rimanere disponibili per un anno o meno a seconda della gravità del problema.

A causa della rapida innovazione e degli sviluppi nell'IA, i servizi basati sull'IA possono avere una disponibilità minima ridotta di un anno. Ogni servizio pubblicherà i criteri di modifica di rilievo.

Qualsiasi servizio di Azure dipendente da un componente non Microsoft può ridurre i criteri di supporto in modo che corrispondano a quello dei criteri del componente. Qualsiasi modifica che causa un'interruzione a causa di questo collegamento al criterio del fornitore del componente che mostra la data in cui il componente non è più supportato.

Versioni di anteprima

In alcuni casi, Microsoft pubblica una versione di anteprima di un servizio per raccogliere commenti e suggerimenti sulle modifiche proposte e sulle nuove funzionalità. Le versioni del servizio di anteprima sono identificate con il suffisso -preview nel relativo api-version , 2022-07-07-previewad esempio .

A meno che non si intenda introdurre in modo esplicito una modifica di rilievo rispetto alla versione stabile precedente, le nuove versioni di anteprima includono tutte le funzionalità della versione stabile più recente e aggiungono nuove funzionalità di anteprima. Tuttavia, tra le versioni di anteprima, un servizio potrebbe interrompere una delle nuove funzionalità di anteprima aggiunte.

Le anteprime non sono destinate all'uso a lungo termine. Ogni volta che diventa disponibile una nuova versione stabile o di anteprima di un servizio, le versioni di anteprima esistenti potrebbero non essere più disponibili a partire da 90 giorni dalla disponibilità della nuova versione. Usare le versioni di anteprima solo nelle situazioni in cui si sviluppa attivamente con nuove funzionalità del servizio e si è pronti ad adottare una nuova versione non di anteprima subito dopo il rilascio. Se alcune funzionalità di una versione di anteprima vengono rilasciate in una nuova versione stabile, le funzionalità rimanenti ancora in anteprima verranno in genere pubblicate in una nuova versione di anteprima.

SDK client e versioni del servizio

Gli SDK di Azure hanno lo scopo di eliminare il controllo delle versioni del servizio come problema durante la scrittura del codice. Ogni SDK è costituito da librerie client, una per ogni servizio e ogni versione della libreria client è destinata a una singola versione del servizio su cui si basa.

Quando si usa un SDK per accedere a un servizio di Azure, per sfruttare le nuove versioni e funzionalità è in genere necessario aggiornare la versione della libreria client usata dall'applicazione. Le nuove versioni stabili dei servizi sono accompagnate da nuove versioni intermedie delle librerie client. Per le nuove versioni delle modifiche di rilievo, le nuove librerie client vengono pubblicate come versioni di rilascio punto o versioni principali. Il tipo di versione dipende dalla natura della modifica del servizio e dal modo in cui la libreria è in grado di adattarla. Solo le librerie client beta-version usano le versioni del servizio di anteprima.

Le librerie client SDK supportano l'override manuale della versione del servizio. L'override della versione predefinita del servizio di una libreria client è uno scenario avanzato e può causare comportamenti imprevisti. Se si usa questa funzionalità, testare attentamente l'applicazione per assicurarsi che funzioni come desiderato.

Strumenti da riga di comando di Azure

Come per gli SDK, gli strumenti da riga di comando di Azure (inclusa l'interfaccia della riga di comando di Azure e Azure PowerShell) sono progettati per consentire l'uso dei servizi di gestione di Azure senza considerare le versioni. L'accesso alle nuove funzionalità del servizio richiede spesso una nuova versione di uno strumento. Le nuove versioni degli strumenti compatibili con le versioni precedenti vengono rilasciate mensilmente. Le versioni con modifiche che causano interruzioni vengono rilasciate circa due volte all'anno o, se necessario, per risolvere i problemi di sicurezza critici.

Gli strumenti da riga di comando di Azure possono esporre occasionalmente funzionalità di anteprima. Questi comandi sono contrassegnati con un'etichetta Preview e generano un avviso che indica un supporto limitato e potenziali modifiche nelle versioni future degli strumenti.