Zásady správy verzí pro služby, sady SDK a nástroje rozhraní příkazového řádku Azure

  • Článek

Většina služeb Azure umožňuje programově řídit a spravovat jejich prostředky pomocí rozhraní REST API. Služby se vyvíjejí prostřednictvím nových publikovaných verzí jejich rozhraní API s různými kontrakty, které přidávají nové funkce nebo upravují jejich chování.

Tento článek popisuje zásady, které týmy Azure Service, SDK a CLI používají ke správě verzí rozhraní Azure REST API. Zatímco týmy Azure se snaží dodržovat tuto zásadu, mohou se občas objevit odchylky.

Správa verzí služby

Každá publikovaná verze rozhraní API je identifikována hodnotou data ve YYYY-MM-DD formátu označované jako api-version. Novější verze mají pozdější data.

Všechny operace rozhraní API vyžadují, aby klienti zadali platnou verzi rozhraní API pro službu prostřednictvím parametru api-version řetězce dotazu v adrese URL. Například: https://management.azure.com/subscriptions?api-version=2020-01-01. Klientské sady SDK a nástroje obsahují api-version hodnotu automaticky. Další důležité informace najdete v části Klientské sady SDK a verze služeb dále v tomto článku.

Publikované verze služeb obvykle zůstávají dostupné a podporované po mnoho let, i když jsou k dispozici novější verze. Ve většiněpřípadůch

Stabilní verze

Většina publikovaných verzí služby je stabilní verze. Stabilní verze jsou zpětně kompatibilní, což znamená, že jakýkoli kód, který píšete, který závisí na jedné verzi služby, může přijmout novější stabilní verzi, aniž by bylo nutné provádět změny kódu, aby se zachovala správnost nebo stávající funkce.

Zásadní změny verzí

Verze zásadní změny služby není zpětně kompatibilní. Přijetí verze zásadní změny v existujícím klientském kódu může vyžadovat změny kódu, aby se zajistilo, že se klient chová přesně tak, jak tomu bylo při cílení na předchozí verzi.

Verze zásadních změn jsou vzácné, oznámeny prostřednictvím dokumentace a obvykle předchází publikování verze Preview. Publikování verze zásadní změny může vyzvat k případnému vyřazení stávajících stabilních verzí, které zůstanou dostupné nejméně tři roky po vydání verze zásadní změny. U zásadních změn publikovaných kvůli problémům se zabezpečením nebo dodržováním předpisů můžou stávající stabilní verze služeb zůstat dostupné po dobu jednoho roku nebo méně v závislosti na závažnosti problému.

Vzhledem k rychlému inovacím a vývoji umělé inteligence mohou mít služby řízené AI nižší minimální dostupnost jednoho roku. Každá služba publikuje zásady zásadních změn.

Jakákoli služba Azure závislá na komponentě jiné společnosti než Microsoft může zmenšit zásady podpory tak, aby odpovídaly zásadám dané komponenty. Jakákoli změna způsobující chybu z důvodu této změny bude odkazovat na zásady dodavatele komponenty zobrazující datum, kdy se komponenta už nepodporuje.

Verze Preview

Microsoft někdy publikuje verzi Preview služby, aby získala zpětnou vazbu k navrhovaným změnám a novým funkcím. Verze služby Preview jsou identifikovány s příponou -preview v jejich api-version - například 2022-07-07-preview.

Pokud explicitně nezamýšleli zavést zásadní změnu z předchozí stabilní verze, zahrnují nové verze Preview všechny funkce nejnovější stabilní verze a přidávají nové funkce ve verzi Preview. Mezi verzemi Preview ale může služba přerušit některou z nově přidaných funkcí preview.

Náhledy nejsou určené pro dlouhodobé použití. Kdykoli bude dostupná nová stabilní verze nebo verze Preview služby, stávající verze Preview můžou být nedostupné až 90 dnů od dostupnosti nové verze. Verze Preview používejte jenom v situacích, kdy aktivně vyvíjíte proti novým funkcím služby a jste připraveni přijmout novou verzi, která není ve verzi Preview, brzy po jejím vydání. Pokud jsou některé funkce z verze Preview vydané v nové stabilní verzi, zbývající funkce se obvykle publikují v nové verzi Preview.

Klientské sady SDK a verze služeb

Sady Azure SDK se zaměřují na odstranění správy verzí služeb jako problému při psaní kódu. Každá sada SDK se skládá z klientských knihoven, jedné pro každou službu a každá verze klientské knihovny cílí na jednu verzi služby, na které spoléhá.

Pokud pro přístup ke službě Azure používáte sadu SDK, při využívání nových verzí a funkcí se obvykle vyžaduje upgrade verze klientské knihovny používané aplikací. Nové stabilní verze služeb jsou doprovázeny novými verzemi klientských knihoven. U nových verzí zásadních změn se nové klientské knihovny publikují jako verze bodu nebo hlavní verze. Typ verze závisí na povaze změny služby a způsobu, jakým ji knihovna dokáže přizpůsobit. Verze služby Preview používají pouze klientské knihovny beta verze.

Klientské knihovny sady SDK podporují ruční přepsání verze služby. Přepsání výchozí verze služby klientské knihovny je pokročilý scénář a může vést k neočekávanému chování. Pokud tuto funkci používáte, důkladně otestujte aplikaci, abyste měli jistotu, že funguje podle potřeby.

Nástroje příkazového řádku Azure

Stejně jako u sad SDK jsou nástroje příkazového řádku Azure (včetně Azure CLI a Azure PowerShellu) navržené tak, aby umožňovaly používání služeb pro správu Azure bez ohledu na verze. Přístup k novým funkcím služby často vyžaduje novou verzi nástroje. Nové zpětně kompatibilní verze nástrojů se vydávají měsíčně. Verze s zásadními změnami se vydávají přibližně dvakrát ročně nebo podle potřeby k opravě kritických problémů se zabezpečením.

Nástroje příkazového řádku Azure můžou občas vystavit funkce preview. Tyto příkazy jsou označené popiskem Preview a vypíše upozornění označující omezenou podporu a potenciální změny v budoucích verzích nástrojů.

Další kroky