Samouczek: Publikowanie wielu wersji interfejsu API

DOTYCZY: Wszystkie warstwy usługi API Management

Istnieją sytuacje, w których niepraktyczne jest użycie tej samej wersji przez wszystkich użytkowników interfejsu API. Gdy konsumenci są gotowi do uaktualnienia do nowszej wersji, preferują proste i zrozumiałe podejście. Jak pokazano w tym samouczku, usługa Azure API Management obsługuje udostępnianie wielu wersji interfejsu API w celu spełnienia tych potrzeb.

Aby uzyskać informacje, zobacz Wersje i poprawki.

Napiwek

Zespoły interfejsów API mogą używać tej funkcji w obszarach roboczych. Obszary robocze zapewniają izolowany dostęp administracyjny do interfejsów API i własnych środowisk uruchomieniowych API.

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
• Wyświetlanie wersji w portalu dla deweloperów

Wymagania wstępne

• Poznaj terminologię usługi Azure API Management.
• Ukończ szybki start Tworzenie wystąpienia usługi Azure API Management.
• Ukończ samouczek Importowanie i publikowanie pierwszego interfejsu API.

Dodawanie nowej wersji

1. W witrynie Azure portal przejdź do instancji API Management.
2. W menu po lewej stronie w sekcji Interfejsy API wybierz pozycję Interfejsy API.
3. Znajdź plik Swagger Petstore — OpenAPI 3.0 na liście interfejsów API. Wybierz wielokropek (...) obok pozycji Swagger Petstore — OpenAPI 3.0 , a następnie wybierz pozycję Dodaj wersję. Dodasz wartości do wynikowego okna w następnej sekcji.

Napiwek

Możesz również włączyć wersje podczas tworzenia nowego interfejsu API. Na ekranie Dodawanie interfejsu API, wybierz Wersja tego interfejsu API?.

Wybieranie schematu przechowywania wersji

W zarządzaniu interfejsem API wybierasz sposób określania wersji, wybierając schemat wersjonowania: ścieżka, nagłówek lub ciąg zapytania. W poniższym przykładzie ścieżka jest używana jako schemat przechowywania wersji.

W oknie Tworzenie nowego interfejsu API jako wersji wprowadź wartości z poniższej tabeli. Następnie wybierz pozycję Utwórz , aby utworzyć wersję.

Ustawienie	Wartość	Opis
Identyfikator wersji	Wersja 1	Wskaźnik specyficzny dla schematu wersji. Dla Ścieżka chodzi o sufiks ścieżki adresu URL interfejsu API.
Schemat przechowywania wersji	Ścieżka	Sposób określania wersji interfejsu API przez osoby wywołujące. W przypadku wybrania pozycji Nagłówek lub Ciąg zapytania wprowadź inną wartość: nazwę nagłówka lub parametru ciągu zapytania. Zostanie wyświetlony przykład użycia.
Pełna nazwa wersji interfejsu API	swagger-petstore-openapi-3-0-v1	Unikalna nazwa w instancji usługi API Management. Ponieważ wersja jest w rzeczywistości nowym interfejsem API opartym na rewizji interfejsu API, ta wartość jest nazwą nowego interfejsu API.
Produkty	Nieograniczone (dostępne w niektórych warstwach usług)	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 zostanie ona wyświetlona na liście interfejsów API w obszarze Swagger Petstore — OpenAPI 3.0 . Zobaczysz teraz dwa interfejsy API: Oryginalny i v1:

Uwaga

Jeśli dodasz wersję do interfejsu API, który nie ma wersji, oryginalna wersja zostanie również automatycznie utworzona. Ta wersja odpowiada na domyślny adres URL. Oryginalna wersja gwarantuje, że połączenia od istniejących rozmówców nadal działają po dodaniu wersji. Jeśli utworzysz nowy interfejs API z włączonymi wersjami od początku, oryginał nie zostanie utworzony.

Edytowanie wersji

Po dodaniu wersji można ją edytować i skonfigurować jako interfejs API, który jest oddzielony od oryginalnego. Zmiany w jednej wersji nie mają wpływu na inną (na przykład w przypadku dodawania lub usuwania operacji interfejsu API lub edytowania specyfikacji interfejsu OpenAPI). Aby uzyskać więcej informacji, zobacz Edytowanie interfejsu API.

Dodawanie wersji do produktu

Aby osoby wywołujące zobaczyły nową wersję, należy ją dodać do produktu. Jeśli nie dodano jeszcze wersji do produktu, możesz to zrobić w dowolnym momencie.

Aby dodać wersję do produktu:

1. W portalu Azure przejdź do wystąpienia usługi API Management.
2. W obszarze Interfejsy API w okienku po lewej stronie wybierz pozycję Produkty.
3. Wybierz produkt, a następnie wybierz pozycję Interfejsy API w okienku po lewej stronie.
4. Wybierz + Dodaj.
5. Wybierz interfejs API.
6. Kliknij opcję Wybierz.

Korzystanie z zestawów wersji

Podczas tworzenia wielu wersji platforma Azure Portal tworzy zbiór wersji, który reprezentuje zestaw wersji dla pojedynczego logicznego interfejsu API. Jeśli wybierzesz nazwę interfejsu API, który ma wiele wersji, w portalu zostanie wyświetlony zestaw wersji. Możesz dostosować nazwę i opis zestawu wersji.

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

• Użyj środowiska Bash w powłoce Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Get started with 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 Uwierzytelnianie na platformie Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Gdy pojawi się monit, zainstaluj rozszerzenie Azure CLI przy pierwszym użyciu. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Używanie rozszerzeń i zarządzanie nimi za pomocą interfejsu 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 api versionset list.

az apim api versionset list --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --output table

Gdy portal Azure tworzy dla ciebie zestaw wersji, przypisuje mu nazwę alfanumeryczną, która pojawia się w kolumnie Nazwa na liście. 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 <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

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

Wyświetlanie wersji w portalu dla deweloperów

Jeśli używasz portalu dla deweloperów, możesz zobaczyć tam wersje interfejsu API.

1. Wybierz pozycję Portal dla deweloperów w górnej części okna.
2. Wybierz API, a następnie Swagger Petstore.
3. Powinna zostać wyświetlona lista rozwijana zawierająca wiele wersji obok nazwy interfejsu API.
4. Wybierz opcję v1.
5. Zwróć uwagę na Adres URL żądania pierwszej operacji na liście. To pokazuje, że ścieżka adresu URL interfejsu API zawiera v1.

Następny krok

Przejdź do następnego samouczka:

Dostosowywanie stylu stron portalu deweloperów