Verziószámozási szabályzat azure-szolgáltatásokhoz, SDK-khoz és PARANCSSOR-eszközökhöz

Cikk
12/13/2023

A legtöbb Azure-szolgáltatás lehetővé teszi, hogy rest API-kkal programozott módon vezérelje és kezelje erőforrásait. A szolgáltatások az API-k új közzétett verzióin keresztül fejlődnek, különböző szerződésekkel, amelyek új funkciókat adnak hozzá és/vagy módosítják viselkedésüket.

Ez a cikk azt a szabályzatot ismerteti, amelyet az Azure-szolgáltatás, az SDK és a CLI-csapatok az Azure REST API-k verziószámozására használnak. Bár az Azure-csapatok mindent megtesznek, hogy betartsák ezt a szabályzatot, időnként előfordulhatnak eltérések.

Szolgáltatás verziószámozása

Az API minden közzétett verzióját egy dátumérték YYYY-MM-DD azonosítja formátumban, az api-versionúgynevezett . Az újabb verziók későbbi dátumokkal rendelkeznek.

Minden API-művelethez az ügyfeleknek érvényes API-verziót kell megadniuk a szolgáltatáshoz az URL-ben található lekérdezési api-version sztring paraméterrel. For example: https://management.azure.com/subscriptions?api-version=2020-01-01. Az ügyféloldali SDK-k és -eszközök automatikusan tartalmazzák az api-version értéket. További szempontokat a jelen cikk későbbi, ügyféloldali SDK-k és szolgáltatásverziók szakaszában talál.

A közzétett szolgáltatásverziók általában hosszú évekig elérhetők és támogatottak maradnak, még akkor is, ha újabb verziók válnak elérhetővé. A legtöbb esetben csak akkor érdemes új szolgáltatásverziót alkalmazni a meglévő kódban, ha kihasználja az új funkciókat.

Stabil verziók

A legtöbb közzétett szolgáltatásverzió stabil verzió. A stabil verziók visszamenőlegesen kompatibilisek, ami azt jelenti, hogy minden olyan kód, amely egy szolgáltatás egy verziójára támaszkodik, egy újabb, stabilabb verziót hozhat létre anélkül, hogy kódmódosításokat kellene végrehajtania a helyesség vagy a meglévő funkciók fenntartása érdekében.

Kompatibilitástörő változásverziók

A szolgáltatás kompatibilitástörő változásverziója nem kompatibilis visszamenőlegesen. A meglévő ügyfélkódban a kompatibilitástörő változás verziójának bevezetése kódmódosítást igényelhet annak biztosításához, hogy az ügyfél pontosan ugyanúgy viselkedjen, mint az előző verzió megcélzásakor.

A kompatibilitástörő változásverziók ritkák, a dokumentáción keresztül jelentik be, és általában egy előzetes verzió közzététele előzi meg. A kompatibilitástörő változás verziójának közzététele a meglévő stabil verziók végleges kivonását eredményezheti, amely a kompatibilitástörő verzió megjelenése után legalább három évig elérhető marad. Biztonsági vagy megfelelőségi problémák miatt közzétett kompatibilitástörő változások esetén a meglévő stabil szolgáltatásverziók a probléma súlyosságától függően egy évig vagy annál rövidebb ideig is elérhetők maradnak.

Az AI gyors innovációja és fejlődése miatt az AI-vezérelt szolgáltatások minimális rendelkezésre állása egy év lehet. Minden szolgáltatás közzéteszi a kompatibilitástörő változási szabályzatát.

A nem Microsoft-összetevőktől függő Azure-szolgáltatások az összetevő házirendjének megfelelően zsugoríthatják a támogatási szabályzatát. Az ebből eredő kompatibilitástörő változások az összetevő gyártójának szabályzatára fognak hivatkozni, amely azt a dátumot jeleníti meg, amikor az összetevő már nem támogatott.

Előzetes verzió

A Microsoft időnként közzétesz egy szolgáltatás előzetes verzióját , hogy visszajelzést gyűjtsön a javasolt módosításokról és új funkciókról. Az előzetes verziójú szolgáltatásverziókat a rendszer az utótaggal -preview azonosítja api-version , például 2022-07-07-preview.

Hacsak nem kifejezetten az előző stabil verzió kompatibilitástörő változását szeretné bevezetni, az új előzetes verziók tartalmazzák a legújabb stabil verzió összes funkcióját, és új előzetes verziójú funkciókat adnak hozzá. Az előzetes verziók között azonban előfordulhat, hogy egy szolgáltatás megszakítja az újonnan hozzáadott előzetes verziójú funkciók bármelyikét.

Az előnézetek nem hosszú távú használatra készültek. Amikor egy szolgáltatás új stabil vagy előzetes verziója elérhetővé válik, a meglévő előzetes verziók az új verzió elérhetőségétől számított 90 napon belül elérhetetlenné válhatnak. Az előzetes verziókat csak olyan helyzetekben használhatja, amikor aktívan fejleszt az új szolgáltatásfunkciók ellen, és készen áll arra, hogy hamarosan új, nem előzetes verziót vezessen be a kiadás után. Ha az előzetes verzió egyes funkciói új stabil verzióban jelennek meg, a még előzetes verzióban lévő többi funkció általában egy új előzetes verzióban lesz közzétéve.

Ügyféloldali SDK-k és szolgáltatásverziók

Az Azure SDK-k célja, hogy kiküszöböljék a szolgáltatások verziószámozását a kódírás során. Minden SDK ügyfélkódtárakból áll, egy-egy szolgáltatáshoz, és minden ügyfélkódtár-verzió a szolgáltatás egyetlen verzióját célozza meg.

Ha SDK-t használ egy Azure-szolgáltatás eléréséhez, az új verziók és funkciók kihasználása általában az alkalmazás által használt ügyfélkódtár-verzió frissítését igényli. A szolgáltatások új stabil verzióit az ügyfélkódtárak új pontkiadásai kísérik. Az új kompatibilitástörő változásverziók esetében az új ügyfélkódtárak pontkiadási vagy fő kiadási verziókként jelennek meg. A kiadás típusa a szolgáltatás változásának jellegétől és a kódtár elhelyezésének módjától függ. Csak a bétaverziós ügyfélkódtárak használnak előzetes verziójú szolgáltatásverziókat.

Az SDK-ügyfélkódtárak támogatják a szolgáltatásverzió manuális felülkonfigurálását. Az ügyfélkódtár alapértelmezett szolgáltatásverziójának felülbírálása speciális forgatókönyv, amely váratlan viselkedéshez vezethet. Ha használja ezt a funkciót, alaposan tesztelje az alkalmazást, hogy biztosan a kívánt módon működjön.

Azure parancssori eszközök

Az SDK-khoz hasonlóan az Azure parancssori eszközei (beleértve az Azure CLI-t és az Azure PowerShellt is) úgy vannak kialakítva, hogy a verzióktól függetlenül engedélyezve legyenek az Azure felügyeleti szolgáltatásai. Az új szolgáltatásfunkciók eléréséhez gyakran szükség van egy eszköz új verziójára. Az új, visszamenőlegesen kompatibilis eszközverziók havonta jelennek meg. A kompatibilitástörő módosításokat tartalmazó verziók évente körülbelül kétszer jelennek meg, vagy a kritikus biztonsági problémák megoldásához szükségesek.

Az Azure parancssori eszközei időnként közzétehetik az előzetes verziójú funkciókat. Ezek a parancsok címkével Preview vannak megjelölve, és figyelmeztetést adnak ki, amely a jövőbeli eszközverziók korlátozott támogatását és lehetséges változásait jelzi.