Share via

Versiebeheerbeleid voor Azure-services, SDK's en CLI-hulpprogramma's

  • Artikel

Met de meeste Azure-services kunt u hun resources programmatisch beheren en beheren met REST API's. Services ontwikkelen zich door nieuwe gepubliceerde versies van hun API's met verschillende contracten die nieuwe functies toevoegen en/of hun gedrag wijzigen.

In dit artikel wordt het beleid beschreven dat de Azure-service, SDK en CLI-teams gebruiken voor het versiebeheer van de Azure REST API's. Hoewel Azure-teams alles in het werk stellen om aan dit beleid te voldoen, kunnen af en toe afwijkingen optreden.

Serviceversiebeheer

Elke gepubliceerde versie van een API wordt geïdentificeerd door een datumwaarde in YYYY-MM-DD indeling, de api-versionzogenaamde . Nieuwere versies hebben latere datums.

Voor alle API-bewerkingen moeten clients een geldige API-versie voor de service opgeven via de api-version queryreeksparameter in de URL. Voorbeeld: https://management.azure.com/subscriptions?api-version=2020-01-01. Client-SDK's en hulpprogramma's bevatten automatisch de api-version waarde. Zie de sectie Client-SDK's en serviceversies verderop in dit artikel voor meer overwegingen.

Normaal gesproken blijven gepubliceerde serviceversies beschikbaar en worden deze jarenlang ondersteund, zelfs als er nieuwere versies beschikbaar komen. In de meeste gevallen moet u alleen een nieuwe serviceversie in bestaande code gebruiken om te profiteren van nieuwe functies.

Stabiele versies

De meeste gepubliceerde serviceversies zijn stabiele versies. Stabiele versies zijn achterwaarts compatibel, wat betekent dat elke code die u schrijft die afhankelijk is van één versie van een service, een nieuwere stabiele versie kan aannemen zonder dat codewijzigingen nodig zijn om de juistheid of bestaande functionaliteit te behouden.

Wijzigingsversies die fouten veroorzaken

Een belangrijke wijzigingsversie van een service is niet compatibel met eerdere versies. Voor het toepassen van een wijzigingsversie die fouten veroorzaken in bestaande clientcode, zijn mogelijk codewijzigingen vereist om ervoor te zorgen dat de client zich precies gedraagt als bij het richten van de vorige versie.

Wijzigingsversies die fouten veroorzaken, worden zelden aangekondigd via documentatie en worden meestal voorafgegaan door publicatie van een preview-versie. Publicatie van een wijzigingsversie die fouten veroorzaken, kan vragen om de uiteindelijke buitengebruikstelling van bestaande stabiele versies, die ten minste drie jaar na de release van de versie van de wijziging die fouten veroorzaken beschikbaar blijft. Voor belangrijke wijzigingen die zijn gepubliceerd vanwege beveiligings- of nalevingsproblemen, kunnen bestaande stabiele serviceversies één jaar of minder beschikbaar blijven, afhankelijk van de ernst van het probleem.

Vanwege de snelle innovatie en ontwikkelingen in AI kunnen AI-gestuurde services een verminderde minimale beschikbaarheid van één jaar hebben. Elke service publiceert het belangrijke wijzigingsbeleid.

Elke Azure-service die afhankelijk is van een niet-Microsoft-onderdeel kan het ondersteuningsbeleid verkleinen zodat het overeenkomt met dat van het beleid van het onderdeel. Elke wijziging die fouten veroorzaakt, wordt gekoppeld aan het beleid van de leverancier van het onderdeel met de datum waarop het onderdeel niet meer wordt ondersteund.

Preview-versies

Af en toe publiceert Microsoft een preview-versie van een service om feedback te verzamelen over voorgestelde wijzigingen en nieuwe functies. Preview-serviceversies worden geïdentificeerd met het achtervoegsel -preview in hun api-version , bijvoorbeeld 2022-07-07-preview.

Tenzij deze expliciet bedoeld is om een belangrijke wijziging van de vorige stabiele versie te introduceren, bevatten nieuwe preview-versies alle functies van de meest recente stabiele versie en voegen nieuwe preview-functies toe. Tussen preview-versies kan een service echter een van de nieuw toegevoegde preview-functies verbreken.

Previews zijn niet bedoeld voor langdurig gebruik. Wanneer een nieuwe stabiele of preview-versie van een service beschikbaar komt, kunnen bestaande preview-versies al 90 dagen na de beschikbaarheid van de nieuwe versie niet meer beschikbaar zijn. Gebruik alleen preview-versies in situaties waarin u actief ontwikkelt op basis van nieuwe servicefuncties en u bent voorbereid op een nieuwe, niet-preview-versie kort nadat deze is uitgebracht. Als sommige functies van een preview-versie worden uitgebracht in een nieuwe stabiele versie, worden de resterende functies die nog in de preview-versie staan, doorgaans gepubliceerd in een nieuwe preview-versie.

Client-SDK's en serviceversies

De Azure SDK's streven ernaar om serviceversiebeheer te elimineren als een probleem bij het schrijven van code. Elke SDK bestaat uit clientbibliotheken, één voor elke service en elke clientbibliotheekversie is gericht op één versie van de service waarvan deze afhankelijk is.

Wanneer u een SDK gebruikt voor toegang tot een Azure-service, moet u de clientbibliotheekversie die door de toepassing wordt gebruikt, doorgaans upgraden van de clientbibliotheekversie die door de toepassing wordt gebruikt. Nieuwe stabiele versies van services worden vergezeld van nieuwe puntreleases van clientbibliotheken. Voor nieuwe belangrijke wijzigingsversies worden nieuwe clientbibliotheken gepubliceerd als puntreleaseversies of primaire releaseversies. Het type release is afhankelijk van de aard van de wijziging van de service en de manier waarop de bibliotheek deze kan opvangen. Alleen clientbibliotheken met bètaversies maken gebruik van preview-serviceversies.

SDK-clientbibliotheken ondersteunen het handmatig overschrijven van de serviceversie. Het overschrijven van de standaardserviceversie van een clientbibliotheek is een geavanceerd scenario en kan leiden tot onverwacht gedrag. Als u deze functie gebruikt, test u uw toepassing grondig om ervoor te zorgen dat deze naar wens werkt.

Azure-opdrachtregelprogramma's

Net als bij de SDK's zijn de Azure-opdrachtregelprogramma's (inclusief de Azure CLI en Azure PowerShell) ontworpen om het gebruik van Azure-beheerservices zonder rekening te houden met versies. Voor het openen van nieuwe servicefuncties is vaak een nieuwe versie van een hulpprogramma vereist. Nieuwe versies van hulpprogramma's die compatibel zijn met eerdere versies, worden maandelijks uitgebracht. Versies met belangrijke wijzigingen worden ongeveer twee keer per jaar uitgebracht, of indien nodig om kritieke beveiligingsproblemen op te lossen.

De Azure-opdrachtregelprogramma's kunnen af en toe preview-functies beschikbaar maken. Deze opdrachten zijn gemarkeerd met een Preview label en geven een waarschuwing weer waarin wordt aangegeven dat er beperkte ondersteuning en mogelijke wijzigingen in toekomstige hulpprogrammaversies worden weergegeven.

Volgende stappen