Samouczek: Użyj wersji poprawionych, aby bezpiecznie wprowadzać nieprzerwane zmiany w interfejsie API

DOTYCZY: Wszystkie warstwy usługi API Management

Gdy interfejs API jest gotowy do pracy i jest używany przez deweloperów, w końcu musisz wprowadzić zmiany w tym interfejsie API i jednocześnie nie zakłócać wywoływania interfejsu API. Ponadto warto poinformować deweloperów o wprowadzanych zmianach.

W usłudze Azure API Management użyj poprawek, aby wprowadzić zmiany interfejsu API powodujące niezgodność, aby bezpiecznie modelować i testować zmiany. Gdy wszystko będzie gotowe, możesz wprowadzić bieżącą poprawkę i zastąpić bieżący interfejs API.

Aby uzyskać podstawowe informacje, zobacz Wersje i poprawki i przechowywanie wersji interfejsu API za pomocą usługi Azure API Management.

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

• Dodawanie nowej poprawki
• Wprowadzanie w poprawce zmian niepowodujących niezgodności
• Ustawianie poprawki jako bieżącej oraz dodawanie wpisu dziennika zmian
• Przeglądanie portalu dla deweloperów w celu wyświetlenia zmian i dziennika zmian

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 poprawki

1. Zaloguj się do witryny Azure Portal i przejdź do wystąpienia usługi API Management.

2. Wybierz pozycję Interfejsy API.

3. Wybierz pozycję Pokazowy interfejs API konferencji z listy interfejsu API (lub inny interfejs API, do którego chcesz dodać poprawki).

4. Wybierz kartę Poprawki .

5. Wybierz pozycję + Dodaj poprawkę.

   

   Napiwek

   Możesz również wybrać pozycję Dodaj poprawkę w menu kontekstowym (...) interfejsu API.

6. Podaj opis nowej poprawki, aby ułatwić zapamiętanie, co będzie używane.

7. Wybierz pozycję Utwórz.

8. Nowa poprawka zostanie utworzona.

   Uwaga

   Oryginalny interfejs API pozostaje w poprawce Poprawka 1. Jest to poprawka, którą nadal będą wywoływać użytkownicy, dopóki nie wybierzesz innej poprawki jako bieżącej.

Wprowadzanie w poprawce zmian niepowodujących niezgodności

1. Z listy interfejsów API wybierz pozycję Wersja demonstracyjna interfejsu API Conference.

2. Wybierz kartę Projektowanie w górnej części ekranu.

3. Zwróć uwagę, że selektor poprawek (bezpośrednio nad kartą projektowania) wskazuje poprawkę Poprawka 2 jako aktualnie wybraną.

   Napiwek

   Za pomocą selektora poprawek możesz przełączać się pomiędzy poprawkami, nad którymi chcesz pracować.

4. Wybierz opcję + Dodaj operację.

5. Ustaw nową operację na POST, a nazwa, nazwa wyświetlana i adres URL operacji jako test.

6. Zapisz nową operację.

   

7. Wprowadzono zmianę w wersji 2. Użyj selektora poprawek w górnej części strony, aby wrócić do wersji 1.

8. Zwróć uwagę, że nowa operacja nie jest wyświetlana w wersji 1.

Ustawianie poprawki jako bieżącej oraz dodawanie wpisu dziennika zmian

Portal

1. Wybierz kartę Poprawki w menu w górnej części strony.

2. Otwórz menu kontekstowe (...) dla poprawki Poprawka 2.

3. Wybierz pozycję Ustaw jako bieżący.

4. Zaznacz pole wyboru Opublikuj w publicznym dzienniku zmian dla tego interfejsu API , jeśli chcesz opublikować notatki dotyczące tej zmiany. Podaj opis zmiany, którą mogą zobaczyć deweloperzy, na przykład: Testowanie poprawek. Dodano nową operację "test".

5. Poprawka 2 jest teraz bieżącą poprawką.

   

Interfejs wiersza polecenia platformy Azure

Aby rozpocząć korzystanie z 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.

Użyj tej procedury, aby utworzyć i zaktualizować wydanie.

1. Uruchom polecenie az apim api list, aby wyświetlić identyfikatory interfejsu API:

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

   Identyfikator interfejsu API do użycia w następnym poleceniu to Name wartość . Poprawka interfejsu API znajduje się w kolumnie ApiRevision .

2. Aby utworzyć wydanie, za pomocą notatki o wersji uruchom polecenie az apim api release create :

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   Wersja, która zostanie wydana, staje się bieżącą wersją.

3. Aby wyświetlić swoje wersje, użyj polecenia az apim api release list :

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   Notatki, które określisz, są wyświetlane w dzienniku zmian. Można je zobaczyć w danych wyjściowych poprzedniego polecenia.

4. Podczas tworzenia wydania --notes parametr jest opcjonalny. Uwagi można dodać lub zmienić później przy użyciu polecenia az apim api release update :

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Użyj wartości w kolumnie Name dla identyfikatora wydania.

Możesz usunąć dowolną wersję, uruchamiając polecenie az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Przeglądanie portalu dla deweloperów w celu wyświetlenia zmian i dziennika zmian

Jeśli wypróbowano portal dla deweloperów, możesz przejrzeć tam zmiany interfejsu API i dziennik zmian.

1. W witrynie Azure Portal wybierz pozycję Interfejsy API.
2. Wybierz pozycję Portal deweloperów z górnego menu.
3. W portalu dla deweloperów wybierz pozycję Interfejsy API, a następnie wybierz pozycję Pokazowy interfejs API konferencji.
4. Zauważ, że nowa operacja test jest teraz dostępna.
5. Wybierz pozycję Dziennik zmian w pobliżu nazwy interfejsu API.
6. Zwróć uwagę, że na liście pojawi się wpis dziennika zmian.

Następne kroki

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

• Dodawanie nowej poprawki
• Wprowadzanie w poprawce zmian niepowodujących niezgodności
• Ustawianie poprawki jako bieżącej oraz dodawanie wpisu dziennika zmian
• Przeglądanie portalu dla deweloperów w celu wyświetlenia zmian i dziennika zmian

Przejdź do następnego samouczka:

Publikowanie wielu wersji interfejsu API