Samouczek: bezpieczne wprowadzanie zmian interfejsu API przy użyciu poprawek

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ć niezwiązane zmiany interfejsu API, 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ć informacje, zobacz Wersje i poprawki.

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

• Dodawanie nowej poprawki
• Wprowadzanie zmian nierozwiązanych z poprawką
• Ustawianie poprawki jako bieżącej oraz dodawanie wpisu dziennika zmian
• Przeglądanie portalu dla deweloperów w celu wyświetlenia zmian i dziennika zmian
• Uzyskiwanie dostępu do poprawki interfejsu API

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. W menu po lewej stronie w obszarze Interfejsy API 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 używanych funkcji.

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 zmian nierozwiązanych z poprawką

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 nazwę wyświetlaną, nazwę 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 przejdź do wystąpienia usługi API Management.
2. W menu po lewej stronie w obszarze Interfejsy API wybierz pozycję Interfejsy API.
3. Wybierz pozycję Portal deweloperów z górnego menu.
4. W portalu dla deweloperów wybierz pozycję Interfejsy API, a następnie wybierz pozycję Pokazowy interfejs API konferencji.
5. Zauważ, że nowa operacja test jest teraz dostępna.
6. Wybierz pozycję Dziennik zmian w pobliżu nazwy interfejsu API.
7. Zwróć uwagę, że na liście pojawi się wpis dziennika zmian.

Uzyskiwanie dostępu do poprawki interfejsu API

Dostęp do każdej poprawki interfejsu API można uzyskać przy użyciu specjalnie sformułowanego adresu URL. Dodaj ;rev={revisionNumber} na końcu ścieżki adresu URL interfejsu API, ale przed ciągiem zapytania, aby uzyskać dostęp do określonej poprawki tego interfejsu API. Na przykład możesz użyć tego adresu URL, aby uzyskać dostęp do wersji 2 interfejsu API konferencji demonstracyjnej:

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

Ścieżki adresów URL dla poprawek interfejsu API można znaleźć na karcie Poprawki w witrynie Azure Portal.

Napiwek

Możesz uzyskać dostęp do bieżącej wersji interfejsu API przy użyciu ścieżki interfejsu API bez ;rev ciągu, oprócz pełnego adresu URL dołączanego ;rev={revisionNumber} do ścieżki interfejsu API.

Podsumowanie

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

• Dodawanie nowej poprawki
• Wprowadzanie zmian nierozwiązanych z poprawką
• Ustawianie poprawki jako bieżącej oraz dodawanie wpisu dziennika zmian
• Przeglądanie portalu dla deweloperów w celu wyświetlenia zmian i dziennika zmian
• Uzyskiwanie dostępu do poprawki interfejsu API

Następne kroki

Przejdź do następnego samouczka:

Publikowanie wielu wersji interfejsu API