Versionsprincip för Azure-tjänster, SDK:er och CLI-verktyg

  • Artikel

Med de flesta Azure-tjänster kan du programmatiskt styra och hantera deras resurser med REST-API:er. Tjänsterna utvecklas genom nya publicerade versioner av sina API:er med olika kontrakt som lägger till nya funktioner och/eller ändrar deras beteenden.

Den här artikeln beskriver den princip som Azure-tjänsten, SDK och CLI-teamen använder för versionshantering av Azure REST-API:er. Även om Azure-teamen gör allt de kan för att följa den här principen kan avvikelser ibland inträffa.

Versionshantering av tjänster

Varje publicerad version av ett API identifieras med ett datumvärde i YYYY-MM-DD formatet , som kallas api-version. Nyare versioner har senare datum.

Alla API-åtgärder kräver att klienter anger en giltig API-version för tjänsten via frågesträngsparametern api-version i URL:en. Exempel: https://management.azure.com/subscriptions?api-version=2020-01-01. Klient-SDK:er och -verktyg inkluderar api-version värdet automatiskt. Mer information finns i avsnittet Klient-SDK:er och tjänstversioner senare i den här artikeln.

Vanligtvis är publicerade tjänstversioner tillgängliga och stöds i många år, även när nyare versioner blir tillgängliga. I de flesta fall är den enda gången du bör använda en ny tjänstversion i befintlig kod att dra nytta av nya funktioner.

Stabila versioner

De flesta publicerade tjänstversioner är stabila versioner. Stabila versioner är bakåtkompatibla, vilket innebär att all kod som du skriver som förlitar sig på en version av en tjänst kan anta en nyare stabil version utan att kräva några kodändringar för att upprätthålla korrekthet eller befintliga funktioner.

Icke-bakåtkompatibla ändringsversioner

En icke-bakåtkompatibel ändringsversion av en tjänst är inte bakåtkompatibel. Om du antar en icke-bakåtkompatibel ändringsversion i befintlig klientkod kan det krävas kodändringar för att säkerställa att klienten fungerar exakt som den gjorde när den riktade sig mot den tidigare versionen.

Icke-bakåtkompatibla ändringsversioner är sällsynta, meddelas via dokumentation och föregås vanligtvis av publicering av en förhandsversion. Publicering av en icke-bakåtkompatibel ändringsversion kan leda till att befintliga stabila versioner kan dras tillbaka, vilket kommer att förbli tillgängligt i minst tre år efter de icke-bakåtkompatibla versionerna. För icke-bakåtkompatibla ändringar som publicerats på grund av säkerhets- eller efterlevnadsproblem kan befintliga stabila tjänstversioner förbli tillgängliga i ett år eller mindre beroende på problemets allvarlighetsgrad.

På grund av den snabba innovationen och utvecklingen inom AI kan AI-drivna tjänster ha en lägsta tillgänglighet på ett år. Varje tjänst publicerar sin policy för icke-bakåtkompatibla ändringar.

Alla Azure-tjänster som är beroende av en icke-Microsoft-komponent kan krympa sin supportprincip så att den matchar komponentens princip. Eventuella icke-bakåtkompatibla ändringar på grund av detta länkar till komponentleverantörens princip som visar det datum då komponenten inte längre stöds.

Förhandsversioner

Ibland publicerar Microsoft en förhandsversion av en tjänst för att samla in feedback om föreslagna ändringar och nya funktioner. Förhandsversioner av tjänsten identifieras med suffixet -preview i deras api-version – till exempel 2022-07-07-preview.

Om det inte uttryckligen är avsett att införa en icke-bakåtkompatibel ändring från den tidigare stabila versionen innehåller nya förhandsversioner alla funktioner i den senaste stabila versionen och lägger till nya förhandsgranskningsfunktioner. Mellan förhandsversioner kan dock en tjänst bryta någon av de nyligen tillagda förhandsgranskningsfunktionerna.

Förhandsversioner är inte avsedda för långsiktig användning. När en ny stabil version eller förhandsversion av en tjänst blir tillgänglig kan befintliga förhandsversioner bli otillgängliga redan 90 dagar från tillgängligheten för den nya versionen. Använd endast förhandsversioner i situationer där du aktivt utvecklar mot nya tjänstfunktioner och du är beredd att anta en ny version som inte är en förhandsversion strax efter att den har släppts. Om vissa funktioner från en förhandsversion släpps i en ny stabil version publiceras vanligtvis återstående funktioner i förhandsversionen i en ny förhandsversion.

Klient-SDK:er och tjänstversioner

Azure SDK:er syftar till att eliminera versionshantering av tjänster som ett problem när du skriver kod. Varje SDK består av klientbibliotek, ett för varje tjänst och varje klientbiblioteksversion riktar sig mot en enda version av den tjänst som den förlitar sig på.

När du använder en SDK för att få åtkomst till en Azure-tjänst kräver användning av nya versioner och funktioner vanligtvis uppgradering av klientbiblioteksversionen som används av programmet. Nya stabila versioner av tjänster åtföljs av nya punktversioner av klientbibliotek. För nya icke-bakåtkompatibla ändringsversioner publiceras nya klientbibliotek som antingen punktversioner eller större versionsversioner. Typen av version beror på vilken typ av tjänst som ändras och hur biblioteket kan hantera det. Endast betaversionsklientbibliotek använder förhandsversioner av tjänsten.

SDK-klientbibliotek stöder manuell åsidosättande av tjänstversionen. Att åsidosätta ett klientbiblioteks standardtjänstversion är ett avancerat scenario och kan leda till oväntat beteende. Om du använder den här funktionen testar du programmet noggrant för att säkerställa att det fungerar som du vill.

Azure-kommandoradsverktyg

Precis som med SDK:erna är Azure-kommandoradsverktygen (inklusive Azure CLI och Azure PowerShell) utformade för att tillåta användning av Azure-hanteringstjänster utan hänsyn till versioner. Åtkomst till nya tjänstfunktioner kräver ofta en ny version av ett verktyg. Nya bakåtkompatibla verktygsversioner släpps varje månad. Versioner med icke-bakåtkompatibla ändringar släpps ungefär två gånger om året, eller vid behov för att åtgärda kritiska säkerhetsproblem.

Azure-kommandoradsverktygen kan ibland exponera förhandsversionsfunktioner. Dessa kommandon är markerade med en Preview etikett och visar en varning som anger begränsat stöd och potentiella ändringar i framtida verktygsversioner.

Nästa steg