Wprowadzenie do centrum interfejsu API
W tym ćwiczeniu wykonasz następujące czynności:
Utwórz usługę Centrum interfejsów API.
Zdefiniuj właściwości metadanych.
Dodaj interfejsy API do Centrum interfejsów API.
Dodawanie wdrożeń i środowisk.
Wymagania wstępne
Aby rozpocząć zarządzanie interfejsami API za pośrednictwem Centrum interfejsów API, potrzebne są następujące elementy:
- Subskrypcja Azure.
- Dostawca zasobów Microsoft.ApiCenter zarejestrowany w twojej subskrypcji.
- Co najmniej przypisanie roli Współautor lub równoważne uprawnienia w subskrypcji platformy Azure.
Uwaga
Jeśli jeszcze tego nie zrobiono, musisz zarejestrować dostawcę zasobów Microsoft.ApiCenter w ramach subskrypcji.
- Zaloguj się do witryny Azure Portal.
- Wprowadź ciąg Subskrypcje na pasku wyszukiwania.
- Wybierz subskrypcję, w której chcesz utworzyć Centrum interfejsów API.
- W menu po lewej stronie w obszarze Zasoby wybierz pozycję Dostawcy zasobów.
- Wyszukaj pozycję Microsoft.ApiCenter na liście dostawców zasobów. Jeśli nie została zarejestrowana, wybierz pozycję Zarejestruj.
Krok 1. Tworzenie usługi Centrum interfejsów API
Wprowadź ciąg Api Centers (Centra interfejsów API) na pasku wyszukiwania.
Wybierz + Utwórz.
Na karcie Podstawowe wybierz lub wprowadź następujące ustawienia:
a. Wybierz subskrypcję platformy Azure.
b. Wybierz istniejącą grupę zasobów lub wybierz pozycję Nowy , aby utworzyć nową.
c. Wprowadź nazwę centrum interfejsu API. Musi być unikatowy w regionie, w którym tworzysz centrum interfejsu API.
d. W obszarze Region wybierz jeden z dostępnych regionów dla centrum interfejsu API.
e. W przypadku planu cenowego wybierz pozycję Bezpłatna wersja próbna ($0 przez 90 dni).
f. Wybierz pozycję Przejrzyj i utwórz.
h. Po zakończeniu walidacji wybierz pozycję Utwórz.
Po wdrożeniu centrum interfejsu API jest gotowe do użycia.
Aby uruchomić polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure i zaloguj się przy użyciu następującego polecenia.
az login
Uwaga
Jeśli jeszcze tego nie zrobiono, musisz zarejestrować dostawcę zasobów Microsoft.ApiCenter w ramach subskrypcji.
Uruchom następujące polecenie, aby zarejestrować dostawcę zasobów
az provider register –namespace Microsoft.ApiCenter
Krok 1. Tworzenie usługi Centrum interfejsów API
Utwórz grupę zasobów, uruchamiając następujące polecenie przekazując następujące polecenie:
- nazwa grupy zasobów — przykład. Contoso
- location — przykład lokalizacji . Eastus
az group create –-name contoso –-location eastus
Uwaga
polecenie az apic wymaga rozszerzenia apic-extension interfejsu wiersza polecenia platformy Azure. Jeśli nie użyto poleceń az apic, rozszerzenie zostanie zainstalowane dynamicznie po uruchomieniu pierwszego polecenia az apic lub można zainstalować rozszerzenie ręcznie. Dowiedz się więcej o rozszerzeniach interfejsu wiersza polecenia platformy Azure.
Utwórz centrum interfejsu API, uruchamiając następujące polecenie, przekazując następujące polecenie:
- Nazwa usługi centrum interfejsu API —n Przykład. contoso-apis
- Grupa zasobów -g Przykład. Contoso
- location --l Przykład. Eastus
az apic create -n contoso-apis -g contoso -l eastus
Uwaga
Domyślnie centrum interfejsów API zostanie utworzone w warstwie cenowej Bezpłatna .
Uwaga
Tworzenie usługi API Center nie jest obecnie obsługiwane w programie VS Code. Utwórz go przy użyciu interfejsu wiersza polecenia platformy Azure lub witryny Azure Portal.
Krok 2. Definiowanie właściwości metadanych
Centrum interfejsów API używa właściwości metadanych do organizowania interfejsów API w spisie i włączania operacji, takich jak filtrowanie, wyszukiwanie itp.
Uwaga
Nie należy uwzględniać żadnych poufnych, poufnych ani osobistych informacji w tytułach/nazwach właściwości metadanych.
Firma Contoso, podobnie jak wiele innych organizacji, chce, aby wszystkie swoje interfejsy API przeszły przez osoby zatwierdzające, zanim staną się dostępne do użycia i upewnij się, że przegląd zgodności jest przeprowadzany dla wszystkich interfejsów API. Organizacja ma również interfejsy API, które są dostępne publicznie, a te utworzone wyłącznie do użytku wewnętrznego. Aby wymusić to na dużą skalę we wszystkich interfejsach API, dodamy trzy niestandardowe właściwości metadanych:
- Osoba zatwierdzająca interfejsu API typu Ciąg
- Przegląd zgodności typu Wstępnie zdefiniowane opcje
- Publiczne oblicze typu logicznego
W menu po lewej stronie wybierz pozycję Metadane > zasobów > i nowe metadane.
Na karcie Szczegóły wprowadź informacje o właściwości .
a. W polu Tytuł wprowadź wartość Osoba zatwierdzająca interfejs API
b. W polu Opis wprowadź wartość Domyślna osoba zatwierdzająca interfejsu API
c. Wybierz typ Ciąg i wybierz przycisk Dalej
Na karcie Przypisania wybierz pozycję Wymagane dla interfejsów API. Wybierz opcję Opcjonalne w obszarze Wdrożenia i środowiska. Wybierz Dalej
Wybierz pozycję Utwórz
Powtórz te same kroki dla właściwości Public-facing , jak pokazano na poniższej ilustracji. Dla typu wybierz wartość logiczną
Na karcie Przypisania wybierz pozycję Wymagane dla interfejsów API. Wybierz pozycję Nie dotyczy wdrożeń i środowisk. Wybierz Dalej
Wybierz pozycję Utwórz
Powtórz te same kroki dla właściwości Compliance-review , jak pokazano na poniższej ilustracji. Dla typu wybierz pozycję Wstępnie zdefiniowane opcje i dodaj 3 opcje , Nie uruchomiono, W toku i Ukończono
Na karcie Przypisania wybierz pozycję Wymagane dla interfejsów API. Wybierz pozycję Nie dotyczy wdrożeń i środowisk
Wybierz Dalej
Schemat metadanych JSON dla interfejsów API jest teraz dostępny do wyświetlania, edytowania i pobierania. Aby wyświetlić, wybierz pozycję Wyświetl schemat metadanych i wybierz z listy rozwijanej pozycję Interfejsy API.
Spowoduje to otwarcie modalne po prawej stronie ze szczegółami metadanych, które obejmują wbudowane właściwości z Centrum interfejsu API, takie jak LifecycleStage, Name, Description, TermsOfService między innymi. Jeśli przewiniesz do dołu pliku, zobaczysz niestandardowe metadane dodane w poprzednich krokach, jak pokazano poniżej.
Uwaga
Właściwości można dodawać i edytować w schemacie w dowolnym momencie i natychmiast stosować do wszystkich interfejsów API w Centrum interfejsów API
Utwórz nowy schemat metadanych, uruchamiając następujące polecenie, aby ustawić następujące polecenie:
- Nazwa metadanych jako osoba zatwierdzająca interfejs API
- Schemat z typem właściwości jako Ciąg i tytuł jako osoba zatwierdzająca interfejsu API
- Przypisania zgodnie z wymaganiami interfejsówAPI, ale opcjonalne dla środowiska i wdrożenia
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Powtórz te same kroki dla:
- Nazwa metadanych jako publiczna
- Schemat z typem właściwości jako wartość logiczną i tytułem publicznym
- Przypisania zgodnie z wymaganiami interfejsówAPI, ale opcjonalne dla środowiska i wdrożenia
Uruchamiając następujące polecenie:
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Na koniec powtórz te same kroki dla:
- Nazwa metadanych jako przegląd zgodności
- Schemat z typem właściwości jako Ciąg i tytuł jako Przegląd zgodności
- Przypisania zgodnie z wymaganiami interfejsówAPI, ale opcjonalne dla środowiska i wdrożenia
Uruchamiając następujące polecenie:
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
Możesz uruchomić następujące polecenie, aby wyświetlić listę wszystkich zdefiniowanych metadanych w Centrum interfejsu API.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Uwaga
Właściwości można dodawać i edytować w schemacie w dowolnym momencie i natychmiast stosować do wszystkich interfejsów API w Centrum interfejsów API
Uwaga
Ta akcja nie jest obecnie obsługiwana w programie VS Code. Utwórz go przy użyciu interfejsu wiersza polecenia platformy Azure lub witryny Azure Portal.
Krok 3. Dodawanie interfejsów API do spisu
Organizacja Contoso chce zalecić konferencje techniczne dla swoich zespołów inżynieryjnych w ramach wewnętrznej umiejętności. Dodamy interfejs API konferencji z prelegentami, sesjami i tematami.
Adres URL interfejsu API konferencji: https://bigconference.azurewebsites.net/
W poniższych krokach możesz skopiować definicję interfejsu OpenAPI z powyższej witryny internetowej i zapisać ją jako plik JSON na komputerze lokalnym. Możesz też zastąpić inną definicję interfejsu API podczas dodawania interfejsu API do spisu.
W portalu przejdź do centrum interfejsu API.
W menu po lewej stronie wybierz pozycję Interfejsy > API zasobów > i zarejestruj interfejs API.
Na stronie Rejestrowanie interfejsu API dodaj następujące wymagane informacje dotyczące interfejsu API. Zobaczysz niestandardowe właściwości metadanych zatwierdzające interfejsu API, *dostępne dla publicznej i zgodności , które zostały zdefiniowane w poprzednich krokach w dolnej części strony.
Aby wyświetlić utworzony interfejs API, w menu po lewej stronie wybierz pozycję > konferencji interfejsów > API zasobów.
Karta Przegląd zawiera widok konfiguracji interfejsu API. Rozwiń węzeł Szczegóły , aby wyświetlić i edytować dodatkowe informacje, takie jak wersja interfejsu API i wdrożenia (w tym momencie nie mamy wdrożeń).
Zwykle chcesz dodać definicję interfejsu API dla wersji interfejsu API, a centrum interfejsów API obsługuje formaty specyfikacji tekstu, w tym OpenAPI 2, OpenAPI 3 dla interfejsu REST.
Aby dodać definicję,
- W menu po lewej stronie wybierz pozycję Interfejsy > API zasobów > Wybierz interfejs API (interfejs API konferencji).
- Rozwiń węzeł Szczegóły i wybierz pozycję Wersje.
- Wybierz swoją wersję (wersja 1) i rozwiń pozycję Szczegóły.
- W obszarze szczegółów wybierz pozycję Definicje > Dodaj definicję.
Rozszerzenie Azure API Center dla programu Visual Studio Code umożliwia zarejestrowanie interfejsu API w wystąpieniu interfejsu API.
Krok 1.Instalowanie rozszerzenia
Krok 2. Otwórz paletę poleceń , "Ctrl + Shift + P" i wpisz API Center: Register API
Postępuj zgodnie z monitami, aby podać następujące informacje dotyczące interfejsu API:
| Rejestrowanie interfejsu API | Krok po kroku |
|---|---|
| Wybieranie usługi API Center | Wybieranie wystąpienia centrum interfejsu API |
| Tytuł interfejsu API | Wprowadź nazwę interfejsu API (interfejs API konferencji) |
| Typ interfejsu API | REST |
| Tytuł wersji interfejsu API | Wprowadź nazwę wersji interfejsu API (wersja 1) |
| Cykl życia wersji interfejsu API | Wybierz cykl życia z listy rozwijanej (Programowanie) |
| Tytuł definicji interfejsu API | Wprowadź nazwę definicji (definicja interfejsu API konferencji) |
| Nazwa specyfikacji interfejsu API | Wybierz specyfikację z listy rozwijanej (OpenAPI 2) |
| Wybieranie pliku definicji interfejsu API do zaimportowania | Przeglądaj i wybierz plik definicji z magazynu |
Odśwież kartę rozszerzenia centrum interfejsu API, a nowo utworzony interfejs API pojawi się w odpowiednim wystąpieniu/zasobie APIC.
Użyj następującego polecenia, aby utworzyć nowy interfejs API, przekazując polecenie :
- Grupa zasobów -g Przykład. Contoso
- Nazwa usługi centrum interfejsu API —n Przykład. contoso-api-center
- Tytuł — przykład. Interfejs API konferencji
- Przykład identyfikatora interfejsu API --api-id . interfejs API konferencji
- Wpisz - typ Przykład. REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
Utwórz wersję interfejsu API przy użyciu następującego polecenia, przekazując następujące polecenie:
- Grupa zasobów -g Przykład. contoso
- Nazwa usługi centrum interfejsu API —n Przykład. contoso-apis
- Przykład identyfikatora interfejsu API --api-id . interfejs API konferencji
- Tytuł — przykład. Wersja 1.2.2
- Identyfikator wersji —-version-id Przykład. 2024-07-03
- Przykład etapu cyklu życia — etap cyklu życia. typu DC2015
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
Możesz również dodać definicję interfejsu API dla swojej wersji interfejsu API, a Centrum interfejsów API obsługuje formaty specyfikacji tekstu, w tym OpenAPI 2, OpenAPI 3 dla interfejsu REST.
Aby dodać definicję, użyj następującego polecenia, przekazując następujące polecenie:
- Grupa zasobów -g Przykład. contoso
- Nazwa usługi centrum interfejsu API —n Przykład. contoso-apis
- Przykład identyfikatora interfejsu API --api-id . interfejs API konferencji
- Identyfikator wersji —-version-id Przykład. 2024-07-03
- Tytuł — przykład. OpenAPI
- Identyfikator definicji — przykład definicji-id . openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
Aby zaimportować plik definicji interfejsu OpenAPI z adresu URL, użyj polecenia az apic api definition import-specification , aby zaimportować element . Przykład: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
Krok 4. Dodawanie wdrożeń i środowisk
Środowiska
Środowisko (programowanie, testowanie, przemieszczanie lub produkcja) reprezentuje lokalizację, w której jest wdrażane środowisko uruchomieniowe interfejsu API. Inżynierowie platformy interfejsu API w firmie Contoso definiują dwa środowiska — testowanie i produkcję w swoim wystąpieniu centrum interfejsu API w celu zarządzania różnymi środowiskami uruchomieniowymi interfejsu API i śledzenia ich w organizacji.
Aby utworzyć środowisko,
W menu po lewej stronie wybierz pozycję Środowiska > zasobów > i nowe środowisko.
Dodaj następujące informacje.
Wybierz pozycję Utwórz.
Powtórz te same kroki dla środowiska produkcyjnego.
Aby utworzyć środowisko, uruchom następujące polecenie interfejsu wiersza polecenia
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
Powtórz to samo dla środowiska produkcyjnego
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
Uwaga
Tworzenie środowisk nie jest obecnie obsługiwane w programie VS Code. W tym kroku użyj interfejsu wiersza polecenia platformy Azure lub witryny Azure Portal.
Wdrożenia
Unikatowa lokalizacja (adres) dla użytkowników korzystających z interfejsu API jest udostępniana dla każdego środowiska uruchomieniowego interfejsu API w danym środowisku. Ta lokalizacja jest nazywana wdrożeniem, a pojedyncza wersja interfejsu API może mieć dwa wdrożenia — przejściowe i produkcyjne.
Firma Contoso ma jeden interfejs API, interfejs API konferencji, który kojarzymy ze utworzonymi środowiskami.
W portalu przejdź do centrum interfejsu API.
W menu po lewej stronie wybierz pozycję Interfejsy API, a następnie wybierz interfejs API, na przykład interfejs API konferencji.
Na stronie Interfejs API konferencji rozwiń węzeł Szczegóły > Wdrożenia > i Dodaj wdrożenie.
Dodaj następujące informacje:
a. Wybierz pozycję Testowanie firmy Contoso z listy rozwijanej dla pola Środowisko .
b. Dla definicji kliknij pozycję Wybierz, wybierz wersję interfejsu API w wersji 1 z listy rozwijanej i wybierz wcześniej dodaną definicję. Kliknij opcję Wybierz.
c. Po pomyślnym dodaniu definicji dodaj podstawowy adres URL środowiska uruchomieniowego, który będzie specyficzny dla interfejsu API w wybranym środowisku.
Aby utworzyć wdrożenie i skojarzyć je ze środowiskiem utworzonym w powyższym kroku, uruchom następujące polecenie interfejsu wiersza polecenia
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
Uwaga
Tworzenie wdrożeń nie jest obecnie obsługiwane w programie VS Code. W tym kroku użyj interfejsu wiersza polecenia platformy Azure lub witryny Azure Portal.