Zasady przechowywania wersji dla usług platformy Azure, zestawów SDK i narzędzi interfejsu wiersza polecenia
Większość usług platformy Azure umożliwia programowe kontrolowanie zasobów i zarządzanie nimi za pomocą interfejsów API REST. Usługi ewoluują dzięki nowym opublikowanym wersjom interfejsów API z różnymi kontraktami, które dodają nowe funkcje i/lub modyfikują swoje zachowania.
W tym artykule opisano zasady używane przez zespoły usługi platformy Azure, zestawu SDK i interfejsu wiersza polecenia do przechowywania wersji interfejsów API REST platformy Azure. Chociaż zespoły platformy Azure dokładają wszelkich starań, aby stosować się do tych zasad, odchylenia mogą występować od czasu do czasu.
Przechowywanie wersji usługi
Każda opublikowana wersja interfejsu API jest identyfikowana przez wartość daty w YYYY-MM-DD formacie o nazwie api-version. Nowsze wersje mają późniejsze daty.
Wszystkie operacje interfejsu API wymagają od klientów określenia prawidłowej wersji interfejsu API dla usługi za pośrednictwem parametru api-version ciągu zapytania w adresie URL. Na przykład: https://management.azure.com/subscriptions?api-version=2020-01-01. Zestawy SDK i narzędzia klienta zawierają api-version wartość automatycznie. Aby uzyskać więcej informacji, zobacz sekcję Zestawy SDK klienta i wersje usług w dalszej części tego artykułu.
Zazwyczaj opublikowane wersje usługi pozostają dostępne i obsługiwane przez wiele lat, nawet gdy nowsze wersje staną się dostępne. W większości przypadków jedynym momentem, w którym należy wdrożyć nową wersję usługi w istniejącym kodzie, jest skorzystanie z nowych funkcji.
Stabilne wersje
Większość opublikowanych wersji usługi to stabilne wersje. Stabilne wersje są zgodne z poprzednimi wersjami, co oznacza, że każdy kod, który jest oparty na jednej wersji usługi, może przyjąć nowszą stabilną wersję bez konieczności wprowadzania zmian w kodzie w celu zachowania poprawności lub istniejącej funkcjonalności.
Wersje zmian powodujących niezgodność
Zmiana powodująca niezgodność wersji usługi nie jest zgodna z poprzednimi wersjami. Wdrożenie wersji zmiany powodującej niezgodność w istniejącym kodzie klienta może wymagać zmian kodu, aby upewnić się, że klient zachowuje się dokładnie tak samo, jak w przypadku określania wartości docelowej poprzedniej wersji.
Wersje zmian powodujących niezgodność są rzadkie, ogłaszane za pośrednictwem dokumentacji i są zwykle poprzedzone publikacją wersji zapoznawczej. Publikacja wersji zmiany powodującej niezgodność może spowodować ewentualne wycofanie istniejących stabilnych wersji, które pozostaną dostępne przez co najmniej trzy lata po wydaniu wersji zmiany powodującej niezgodność. W przypadku zmian powodujących niezgodność opublikowanych z powodu problemów z zabezpieczeniami lub zgodności istniejące stabilne wersje usługi mogą pozostać dostępne przez jeden rok lub mniej w zależności od ważności problemu.
Ze względu na szybkie innowacje i rozwój sztucznej inteligencji usługi oparte na sztucznej inteligencji mogą mieć obniżoną minimalną dostępność przez rok. Każda usługa opublikuje zasady zmiany powodującej niezgodność.
Każda usługa platformy Azure zależna od składnika innego niż Microsoft może zmniejszyć swoje zasady pomocy technicznej, aby dopasować je do zasad składnika. Każda zmiana powodująca niezgodność będzie łączyć się z zasadami dostawcy składników pokazującymi datę, gdy składnik nie jest już obsługiwany.
Wersje wersji zapoznawczej
Czasami firma Microsoft publikuje wersję zapoznawcza usługi w celu zebrania opinii na temat proponowanych zmian i nowych funkcji. Wersje usługi w wersji zapoznawczej są identyfikowane z sufiksem -preview w pliku api-version , na przykład 2022-07-07-preview.
O ile nie ma jawnie na celu wprowadzenia zmiany powodującej niezgodność z poprzedniej stabilnej wersji, nowe wersje zapoznawcza obejmują wszystkie funkcje najnowszej stabilnej wersji i dodają nowe funkcje w wersji zapoznawczej. Jednak między wersjami zapoznawcza usługa może przerwać dowolną z nowo dodanych funkcji w wersji zapoznawczej.
Wersje zapoznawcze nie są przeznaczone do długoterminowego użytku. Gdy nowa stabilna lub zapoznawcza wersja usługi stanie się dostępna, istniejące wersje wersji zapoznawczej mogą stać się niedostępne już od 90 dni od dostępności nowej wersji. Korzystaj z wersji zapoznawczych tylko w sytuacjach, w których aktywnie opracowujesz nowe funkcje usługi i przygotowujesz się do wdrożenia nowej, innej niż wersja zapoznawcza wkrótce po jej wydaniu. Jeśli niektóre funkcje z wersji zapoznawczej są wydawane w nowej stabilnej wersji, pozostałe funkcje nadal w wersji zapoznawczej będą zwykle publikowane w nowej wersji zapoznawczej.
Zestawy SDK klienta i wersje usług
Zestawy SDK platformy Azure mają na celu wyeliminowanie obsługi wersji usługi jako problemu podczas pisania kodu. Każdy zestaw SDK składa się z bibliotek klienckich, po jednym dla każdej usługi, a każda wersja biblioteki klienta jest przeznaczona dla pojedynczej wersji usługi, na której polega.
Gdy używasz zestawu SDK do uzyskiwania dostępu do usługi platformy Azure, korzystanie z nowych wersji i funkcji zwykle wymaga uaktualnienia wersji biblioteki klienta używanej przez aplikację. Nowe stabilne wersje usług są dołączane przez nowe wersje punktów bibliotek klienckich. W przypadku nowych wersji zmian powodujących niezgodność nowe biblioteki klienckie są publikowane jako wersje wydania punktu lub wersje wersji głównych. Typ wydania zależy od charakteru zmiany usługi i sposobu, w jaki biblioteka może ją pomieścić. Tylko biblioteki klienckie w wersji beta używają wersji zapoznawczych.
Biblioteki klienckie zestawu SDK obsługują ręczne zastępowanie wersji usługi. Zastępowanie domyślnej wersji usługi biblioteki klienta jest zaawansowanym scenariuszem i może prowadzić do nieoczekiwanego zachowania. Jeśli używasz tej funkcji, przetestuj aplikację dokładnie, aby upewnić się, że działa zgodnie z potrzebami.
Narzędzia wiersza polecenia platformy Azure
Podobnie jak w przypadku zestawów SDK, narzędzia wiersza polecenia platformy Azure (w tym interfejs wiersza polecenia platformy Azure i program Azure PowerShell) są przeznaczone do zezwalania na korzystanie z usług zarządzania platformy Azure bez względu na wersje. Uzyskiwanie dostępu do nowych funkcji usługi często wymaga nowej wersji narzędzia. Nowe wersje narzędzi zgodne z poprzednimi wersjami są wydawane co miesiąc. Wersje z zmianami powodujących niezgodność są wydawane mniej więcej dwa razy w roku lub zgodnie z wymaganiami w celu rozwiązania krytycznych problemów z zabezpieczeniami.
Narzędzia wiersza polecenia platformy Azure mogą czasami uwidaczniać funkcje w wersji zapoznawczej. Te polecenia są oznaczone etykietą Preview i będą zwracać ostrzeżenie wskazujące ograniczoną obsługę i potencjalne zmiany w przyszłych wersjach narzędzi.