Wersje w usłudze Azure API Management

DOTYCZY: Wszystkie warstwy usługi API Management

Wersje umożliwiają prezentowanie grup powiązanych interfejsów API Twoim deweloperom. Możesz bezpiecznie obsługiwać zmiany powodujące niezgodność w Twoim interfejsie API przy użyciu wersji. Klienci mogą zdecydować się na korzystanie z nowej wersji interfejsu API, gdy będą gotowi, podczas gdy obecni klienci nadal korzystają ze starszej wersji. Wersje są rozróżniane za pomocą identyfikatora wersji (który jest dowolnym wybranym przez Ciebie ciągiem znaków), a schemat przechowywania wersji pozwala klientom określić, z której wersji interfejsu API chcą korzystać.

Dla większości celów, każda wersja interfejsu API może być uważana za własny, niezależny interfejs API. Dwie różne wersje interfejsu API mogą mieć różne zestawy operacji i różne zasady.

W przypadku wersji można wykonywać następujące czynności:

• Opublikuj wiele wersji interfejsu API w tym samym czasie.
• Użyj ścieżki, ciągu zapytania lub nagłówka, aby odróżnić wersje.
• Użyj dowolnej wartości ciągu, którą chcesz zidentyfikować, która może być liczbą, datą lub nazwą.
• Pokaż wersje interfejsu API pogrupowane razem w portalu dla deweloperów.
• Przejmij istniejący (bez wersji) interfejs API i utwórz nową wersję bez przerywania działania istniejących klientów.

Rozpocznij pracę z wersjami, postępując zgodnie z naszym przewodnikiem.

Schematy przechowywania wersji

Różni deweloperzy interfejsu API mają różne wymagania dotyczące przechowywania wersji. Usługa Azure API Management nie określa pojedynczego podejścia do przechowywania wersji, ale udostępnia kilka opcji.

Przechowywanie wersji opartej na ścieżkach

W przypadku użycia schematu przechowywania wersji ścieżki identyfikator wersji musi być uwzględniony w ścieżce adresu URL dla wszystkich żądań interfejsu API.

Na przykład i https://apis.contoso.com/products/v2 może odwoływać się do tego samego products interfejsu API, https://apis.contoso.com/products/v1 ale do wersji v1 i v2 odpowiednio.

Format adresu URL żądania interfejsu API w przypadku korzystania z przechowywania wersji opartej na ścieżkach to: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Przechowywanie wersji na podstawie nagłówka

Gdy jest używany schemat przechowywania wersji nagłówka, identyfikator wersji musi być uwzględniony w nagłówku żądania HTTP dla wszystkich żądań interfejsu API. Możesz określić nazwę nagłówka żądania HTTP.

Na przykład można utworzyć niestandardowy nagłówek o nazwie Api-Version, a klienci mogą określić v1 lub v2 w wartości tego nagłówka.

Przechowywanie wersji na podstawie ciągów zapytań

Gdy jest używany schemat przechowywania wersji ciągu zapytania, identyfikator wersji musi być uwzględniony w parametrze ciągu zapytania dla wszystkich żądań interfejsu API. Możesz określić nazwę parametru ciągu zapytania.

Format adresu URL żądania interfejsu API w przypadku używania przechowywania wersji opartej na ciągu zapytania to: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Na przykład i https://apis.contoso.com/products?api-version=v2 może odwoływać się do tego samego products interfejsu API, https://apis.contoso.com/products?api-version=v1 ale do wersji v1 i v2 odpowiednio.

Uwaga

Parametry zapytania nie są dozwolone we servers właściwości specyfikacji interfejsu OpenAPI. Jeśli wyeksportujesz specyfikację interfejsu OpenAPI z wersji interfejsu API, ciąg zapytania nie będzie wyświetlany w adresie URL serwera.

Oryginalne wersje

Jeśli dodasz wersję do interfejsu API bez wersji, Original wersja zostanie automatycznie utworzona i odpowie na domyślny adres URL bez określonego identyfikatora wersji. Wersja Original gwarantuje, że wszystkie istniejące osoby wywołujące nie zostaną przerwane przez proces dodawania wersji. Jeśli tworzysz nowy interfejs API z włączonymi wersjami na początku, Original wersja nie zostanie utworzona.

Jak są reprezentowane wersje

Usługa Azure API Management obsługuje zasób nazywany zestawem wersji, który reprezentuje zestaw wersji dla pojedynczego logicznego interfejsu API. Zestaw wersji zawiera nazwę wyświetlaną wersji interfejsu API oraz schemat przechowywania wersji używany do kierowania żądań do określonych wersji.

Każda wersja interfejsu API jest utrzymywana jako własny zasób interfejsu API, który jest następnie skojarzony z zestawem wersji. Zestaw wersji może zawierać interfejsy API z różnymi operacjami lub zasadami. Możesz wprowadzić istotne zmiany między wersjami w zestawie.

Witryna Azure Portal tworzy zestawy wersji. Możesz zmodyfikować nazwę i opis wersji ustawionej w witrynie Azure Portal.

Zestaw wersji jest automatycznie usuwany po usunięciu ostatecznej wersji.

Zestawy wersji można wyświetlać i zarządzać nimi bezpośrednio przy użyciu interfejsu wiersza polecenia platformy Azure, programu Azure PowerShell, szablonów usługi Resource Manager lub interfejsu API usługi Azure Resource Manager.

Uwaga

Wszystkie wersje w zestawie wersji mają ten sam schemat przechowywania wersji na podstawie schematu przechowywania wersji używanego podczas pierwszego dodawania wersji do interfejsu API.

Migrowanie nieodpartego interfejsu API do wersji interfejsu API

Jeśli używasz witryny Azure Portal do włączania przechowywania wersji w istniejącym interfejsie API, następujące zmiany są wprowadzane do zasobów usługi API Management:

• Zostanie utworzony nowy zestaw wersji.
• Istniejąca wersja jest utrzymywana i konfigurowana jako wersja interfejsu Original API. Interfejs API jest połączony z zestawem wersji, ale nie wymaga określenia identyfikatora wersji.
• Nowa wersja jest tworzona jako nowy interfejs API i jest połączona z zestawem wersji. Ten nowy interfejs API musi być dostępny przy użyciu schematu przechowywania wersji i identyfikatora.

Wersje i poprawki

Wersje i poprawki są odrębnymi funkcjami. Każda wersja może mieć wiele poprawek, podobnie jak interfejs API, który nie jest w wersji. Można używać poprawek bez używania wersji lub odwrotnie. Zazwyczaj wersje są używane do rozdzielania wersji interfejsu API zmianami powodujących niezgodność, podczas gdy poprawki mogą być używane do drobnych i niełamających się zmian w interfejsie API.

Jeśli okaże się, że poprawka zawiera zmiany powodujące niezgodność lub jeśli chcesz formalnie przekształcić poprawkę w wersję beta/testową, możesz utworzyć wersję na podstawie poprawki. W witrynie Azure Portal kliknij pozycję "Utwórz wersję z poprawki" w menu kontekstowym poprawek na karcie Poprawki.

Portal deweloperów

Portal dla deweloperów wyświetla oddzielnie każdą wersję interfejsu API.

Szczegóły interfejsu API zawierają również listę wszystkich wersji tego interfejsu API. Wersja jest wyświetlana Original bez identyfikatora wersji.

Napiwek

Wersje interfejsu API należy dodać do produktu, zanim będą widoczne w portalu dla deweloperów.