Nadzór nad interfejsem API

Ukończone

Ład interfejsu API jest definiowany jako praktyka definiowania i stosowania standardów, zasad i procesów na dużą skalę we wszystkich interfejsach API organizacji. Centrum interfejsów API umożliwia wykonanie tych czynności za pomocą:

• Metadane interfejsu API śledzenia, w tym tytuł interfejsu API, opis, wersje, definicje i wdrożenia. Ponadto można określić własne niestandardowe metadane interfejsu API — takie jak informacje o witrynie na żywo, repozytorium kontroli źródła itp. — w celu śledzenia metadanych ważnych dla organizacji (pokazanych we wcześniejszym module).
• Zapewnienie, że wszystkie interfejsy API zostały zaprojektowane tak, aby były zgodne z założeniami projektowania interfejsu API organizacji
• Zapewnianie terminowego wykrywania wersji interfejsu API przy użyciu zmian powodujących niezgodność w celu bezproblemowego wdrażania i komunikacji z użytkownikami interfejsu API

W tej lekcji zobaczymy, jak centrum interfejsów API umożliwia konfigurowanie ładu interfejsu API na dużą skalę.

Wymagania wstępne

Aby zarządzać interfejsami API za pomocą centrum interfejsów API, należy wykonać następujące kroki:

1. Zainstaluj interfejs wiersza polecenia platformy Azure.
2. Zainstaluj interfejs wiersza polecenia dla deweloperów platformy Azure (azd).
3. Zarejestruj dostawcę zasobów usługi Event Grid w ramach subskrypcji. Jeśli musisz zarejestrować dostawcę zasobów usługi Event Grid, zobacz Subskrybowanie zdarzeń opublikowanych przez partnera z usługą Azure Event Grid.

Zgodność projektu interfejsu API

Zespoły platformy interfejsu API są często odpowiedzialne za definiowanie zestawu wytycznych dla producentów interfejsów API. Centrum interfejsów API umożliwia kodowanie wytycznych interfejsu API przez definiowanie reguł za pomocą aparatu lintingu typu open source Spectral . Domyślnie centrum interfejsów API zawiera podaną regułę spectral, ale zawsze można tworzyć własne lub korzystać z dużej społeczności zestawów reguł typu open source. Za każdym razem, gdy definicja interfejsu API zostanie przekazana, centrum interfejsu API uruchamia linter Spectral przy użyciu podanego zestawu reguł, aby sprawdzić definicję interfejsu API pod kątem zgodności z regułą. Zostanie wygenerowany raport zgodności interfejsu API, który można wyświetlić w centrum interfejsu API.

Aby skonfigurować zgodność projektu interfejsu API dla organizacji:

1. Sklonuj repozytorium GitHub i otwórz je w programie Visual Studio Code.

2. Zmień katalog na APICenter-Analyzer folder w repozytorium.

3. W folderze resources/rulesets można znaleźć oas.yaml plik. Ten plik odzwierciedla bieżący przewodnik po stylu interfejsu API i można go modyfikować na podstawie potrzeb i wymagań organizacji.

4. Uwierzytelnianie za pomocą interfejsu wiersza polecenia dla deweloperów platformy Azure i interfejsu wiersza polecenia platformy Azure przy użyciu następujących poleceń:

   azd auth login
   
   az login
   

5. Uruchom następujące polecenie, aby wdrożyć infrastrukturę linting w ramach subskrypcji platformy Azure.

   azd up
   

6. Postępuj zgodnie z monitami, aby podać wymagane informacje i ustawienia wdrożenia, takie jak nazwa środowiska i nazwa centrum interfejsu API. Aby uzyskać szczegółowe informacje, zobacz Uruchamianie przykładu przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure (azd).

   Uwaga

   Wdrożenie może potrwać kilka minut.

7. Po zakończeniu wdrażania przejdź do centrum interfejsu API w witrynie Azure Portal. W menu po lewej stronie wybierz pozycję Subskrypcje zdarzeń zdarzeń>, aby wyświetlić utworzoną subskrypcję zdarzeń.

Teraz możesz przekazać plik definicji interfejsu API do centrum interfejsu API, aby wyzwolić subskrypcję zdarzeń i uruchomić aparat lintingu.

Shift-left API governance

Najbardziej udane inicjatywy ładu zawsze obejmują deweloperów. Stosując tradycyjne zasady zmiany w lewo, zespoły platformy interfejsów API mogą zapewnić, że producenci interfejsów API wiedzą dokładnie, jakie wymagania muszą spełnić, aby publikować interfejsy API na wczesnym etapie cyklu programowania. Pozwala to zaoszczędzić cenny czas programowania, zmniejszając konieczność korygowania niezgodnych interfejsów API w dalszej części cyklu programowania.

Rozszerzenie Centrum interfejsu API dla programu Visual Studio Code udostępnia producentom interfejsów API środowisko umożliwiające uruchamianie testów zgodności interfejsu API bezpośrednio w programie Visual Studio Code podczas kompilowania interfejsu API. Ponadto producenci interfejsów API mogą używać funkcji wykrywania zmian powodujących niezgodność, aby wykryć, kiedy zmiana może spowodować niezgodność czatu dla użytkowników interfejsu API.

Zgodność projektu interfejsu API w programie Visual Studio Code

Rozszerzenie centrum interfejsu API jest zintegrowane z językiem Spectral, linterem JSON/YAML obsługującym interfejs OpenAPI i niestandardowy zestaw reguł. Rozszerzenie umożliwia deweloperom ścisłe przestrzeganie podanego lub zalecanego przewodnika po stylu interfejsu API, zapewniając spójność we wszystkich interfejsach API opracowywanych w różnych zespołach.

Uwaga

Aby korzystać z tej funkcji, należy zainstalować centrum interfejsów API i rozszerzenia spectral .

Aby aktywować,

1. Użyj skrótu klawiaturowego Ctrl+Shift+P , aby otworzyć paletę poleceń. Wpisz Centrum interfejsów API platformy Azure: ustaw aktywny przewodnik stylu interfejsu API i naciśnij Enter.
2. Wybierz jedną z podanych reguł domyślnych lub, jeśli organizacja ma już dostępny przewodnik stylu, użyj pozycji Wybierz lokalny plik lub zdalny adres URL danych wejściowych, aby określić aktywny zestaw reguł w programie Visual Studio Code. Naciśnij Enter.

Po ustawieniu aktywnego przewodnika stylu interfejsu API otwieranie dowolnego pliku specyfikacji opartego na standardzie OpenAPI lub AsyncAPI wyzwala lokalną operację lintingu w programie Visual Studio Code. Wyniki są wyświetlane zarówno w tekście w edytorze, jak i w oknie Problemy (Wyświetl > problemy lub Ctrl+Shift+M).

Wykrywanie zmian powodujących niezgodność w programie Visual Studio Code

Wersje interfejsu API wysyłki, które przerywają przepływy pracy produkcyjne klienta, skutkuje brakiem odpowiedzialności i utratą zaufania. Rozszerzenie API Center korzystające z optyki umożliwia deweloperom łatwe porównywanie dwóch wersji interfejsu API i wykrywanie wszelkich zmian powodujących niezgodność wprowadzonych do interfejsu API przed wdrożeniem.

Uwaga

Aby korzystać z tej możliwości, należy zainstalować platformę Optic. Zainstaluj przy użyciu następującego polecenia.

*npm install -g @useoptic/optic*

Następnie

1. Użyj skrótu klawiaturowego Ctrl+Shift+P , aby otworzyć paletę poleceń. Wpisz Centrum interfejsów API platformy Azure: Wykrywanie zmian powodujących niezgodność i naciśnij Enter.
2. Wybierz pierwszy dokument specyfikacji interfejsu API do porównania. Prawidłowe opcje obejmują specyfikacje interfejsu API znalezione w centrum interfejsu API, pliku lokalnego lub aktywnego edytora w programie Visual Studio Code.
3. Wybierz drugi dokument specyfikacji interfejsu API do porównania. Prawidłowe opcje obejmują specyfikacje interfejsu API znalezione w centrum interfejsu API, pliku lokalnego lub aktywnego edytora w programie Visual Studio Code.

Program Visual Studio Code otwiera widok różnic między dwoma specyfikacjami interfejsu API. Wszelkie zmiany powodujące niezgodność są wyświetlane zarówno w tekście w edytorze, jak i w oknie Problemy (Wyświetl > problemy lub Ctrl+Shift+M).