Samouczek: Publikowanie wielu wersji interfejsu API

DOTYCZY: Wszystkie warstwy usługi API Management

Czasami niepraktyczne jest, aby wszystkie osoby wywołujące interfejs API używały dokładnie tej samej wersji. Gdy osoby wywołujące chcą przeprowadzić uaktualnienie do nowszej wersji, chcą poznać podejście, które jest łatwe do zrozumienia. Jak pokazano w tym samouczku, można udostępnić wiele wersji w usłudze Azure API Management.

Aby uzyskać informacje na temat tła, zobacz Wersje i poprawki.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Dodawanie nowej wersji do istniejącego interfejsu API
• Wybieranie schematu wersji
• Dodawanie wersji do produktu
• Przeglądanie portalu dla deweloperów w celu wyświetlenia wersji

Wymagania wstępne

• Poznaj terminologię dotyczącą usługi Azure API Management.
• Wykonaj procedury przedstawione w następującym przewodniku Szybki start: Tworzenie wystąpienia usługi Azure API Management.
• Ponadto wykonaj zadania z następującego samouczka: Importowanie i publikowanie pierwszego interfejsu API.

Dodawanie nowej wersji

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.
2. Wybierz pozycję Interfejsy API.
3. Z listy interfejsów API wybierz pozycję Wersja demonstracyjna interfejsu API Conference.
4. Wybierz menu kontekstowe (...) obok pozycji Pokazowy interfejs API konferencji.
5. Wybierz pozycję Dodaj wersję.

Napiwek

Wersje można również włączyć podczas tworzenia nowego interfejsu API. Na ekranie Dodawanie interfejsu API wybierz pozycję Wersja tego interfejsu API?.

Wybieranie schematu przechowywania wersji

W usłudze Azure API Management możesz wybrać sposób określania wersji interfejsu API przez wybranie schematu przechowywania wersji: ścieżka, nagłówek lub ciąg zapytania. W poniższym przykładzie ścieżka jest używana jako schemat przechowywania wersji.

Wprowadź wartości z poniższej tabeli. Następnie wybierz pozycję Utwórz , aby utworzyć wersję.

Ustawienie	Wartość	Opis
Nazwa/nazwisko	demo-conference-api-v1	Unikatowa nazwa w wystąpieniu usługi API Management. Ponieważ wersja jest w rzeczywistości nowym interfejsem API opartym na poprawce interfejsu API, to ustawienie jest nazwą nowego interfejsu API.
Schemat przechowywania wersji	Ścieżka	Sposób określania wersji interfejsu API przez osoby wywołujące.
Identyfikator wersji	Wersja 1	Wskaźnik specyficzny dla schematu wersji. W polu Ścieżka sufiks ścieżki adresu URL interfejsu API. Jeśli wybrano pozycję Nagłówek lub Ciąg zapytania, wprowadź dodatkową wartość: nazwę nagłówka lub parametru ciągu zapytania. Zostanie wyświetlony przykład użycia.
Produkty	Unlimited (nieograniczony)	Opcjonalnie co najmniej jeden produkt skojarzony z wersją interfejsu API. Aby opublikować interfejs API, musisz skojarzyć go z produktem. Możesz również dodać wersję do produktu później.

Po utworzeniu wersji jest ona teraz wyświetlana poniżej interfejsu API konferencji demonstracyjnej na liście interfejsów API . Zobaczysz teraz dwa interfejsy API: Original i v1.

Uwaga

Jeśli dodasz wersję do interfejsu API bez wersji, zostanie również automatycznie utworzony oryginał . Ta wersja odpowiada na domyślny adres URL. Utworzenie oryginalnej wersji gwarantuje, że żadne istniejące osoby wywołujące nie zostaną przerwane przez proces dodawania wersji. Jeśli na początku utworzysz nowy interfejs API z włączonymi wersjami, oryginalny element nie zostanie utworzony.

Edytowanie wersji

Po dodaniu wersji możesz teraz edytować i skonfigurować ją jako interfejs API, który jest oddzielony od oryginalnego. Zmiany wprowadzane w jednej wersji nie wpływają na drugą. Na przykład dodaj lub usuń operacje interfejsu API albo edytuj specyfikację interfejsu OpenAPI. Aby uzyskać więcej informacji, zobacz Edytowanie interfejsu API.

Dodawanie wersji do produktu

Aby wywołujący mogli zobaczyć nową wersję, musi zostać ona dodana do produktu. Jeśli nie dodano jeszcze wersji do produktu, możesz dodać ją do produktu w dowolnym momencie.

Aby na przykład dodać wersję do produktu Unlimited :

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.
2. Wybierz pozycję Products Unlimited APIs+ Add (Interfejsy API bez ograniczeń>produktów>> i dodaj).
3. Wybierz pozycję Pokazowy interfejs API konferencji, wersja 1.
4. Kliknij opcję Wybierz.

Korzystanie z zestawów wersji

Podczas tworzenia wielu wersji witryna Azure Portal tworzy zestaw wersji, który reprezentuje zestaw wersji dla pojedynczego logicznego interfejsu API. Wybierz nazwę interfejsu API, który ma wiele wersji. W witrynie Azure Portal zostanie wyświetlony zestaw wersji. Możesz dostosować nazwę i opis zestawu wirtualnego.

Bezpośrednie interakcje z zestawami wersji można wykonywać przy użyciu interfejsu wiersza polecenia platformy Azure:

• Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.

  

• Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.

  • Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.

  • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.

Aby wyświetlić wszystkie zestawy wersji, uruchom polecenie az apim apim api versionset list :

az apim api versionset list --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --output table

Gdy witryna Azure Portal utworzy zestaw wersji, przypisuje ona nazwę alfanumeryczną wyświetlaną w kolumnie Nazwa listy. Użyj tej nazwy w innych poleceniach interfejsu wiersza polecenia platformy Azure.

Aby wyświetlić szczegółowe informacje o zestawie wersji, uruchom polecenie az apim api versionset show :

az apim api versionset show --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

Aby uzyskać więcej informacji na temat zestawów wersji, zobacz Wersje w usłudze Azure API Management.

Przeglądanie portalu dla deweloperów w celu wyświetlenia wersji

Jeśli wypróbowano portal dla deweloperów, możesz zobaczyć tam wersje interfejsu API.

1. Wybierz opcję Portal dla deweloperów z górnego menu.
2. Wybierz pozycję Interfejsy API, a następnie wybierz pozycję Wersja demonstracyjna interfejsu API Conference.
3. Obok nazwy interfejsu API powinna zostać wyświetlona lista rozwijana z wieloma wersjami.
4. Wybierz opcję v1.
5. Zwróć uwagę na Adres URL żądania pierwszej operacji na liście. Pozycja pokazuje, że ścieżka adresu URL interfejsu API uwzględnia ciąg v1.

Następne kroki

W tym samouczku zawarto informacje na temat wykonywania następujących czynności:

• Dodawanie nowej wersji do istniejącego interfejsu API
• Wybieranie schematu wersji
• Dodawanie wersji do produktu
• Przeglądanie portalu dla deweloperów w celu wyświetlenia wersji

Przejdź do następnego samouczka:

Dostosowywanie stylu stron portalu deweloperów