Włączanie analizy interfejsu API w centrum interfejsu API — samodzielne zarządzanie

W tym artykule wyjaśniono, jak włączyć analizę interfejsu API w centrum interfejsu API platformy Azure, ręcznie konfigurując aparat linting i wyzwalacze. Te funkcje analizują definicje interfejsu API pod kątem przestrzegania reguł stylu organizacji, generując raporty zarówno indywidualne, jak i podsumowania. Analiza interfejsu API pomaga identyfikować i naprawiać typowe błędy i niespójności w definicjach interfejsu API.

Uwaga

W wersji zapoznawczej centrum interfejsów API platformy Azure automatycznie konfiguruje domyślny aparat linting i zależności na potrzeby analizy interfejsu API. Jeśli włączysz analizę zarządzaną samodzielnie zgodnie z opisem w tym artykule, zastąpisz te wbudowane funkcje.

Omówienie scenariusza

W tym scenariuszu analizujesz definicje interfejsu API w centrum interfejsu API przy użyciu aparatu linting typu open source Spectral . Aplikacja usługi Azure Functions uruchamia aparat lintingu w odpowiedzi na zdarzenia w centrum interfejsu API. Spectral sprawdza, czy interfejsy API zdefiniowane w dokumencie specyfikacji JSON lub YAML są zgodne z regułami w dostosowywalnym przewodniku stylu interfejsu API. Zostanie wygenerowany raport analizy, który można wyświetlić w centrum interfejsu API.

Na poniższym diagramie przedstawiono kroki umożliwiające włączenie lintingu i analizy w centrum interfejsu API.

1. Wdróż aplikację usługi Azure Functions, która uruchamia aparat lintingu Spectral w definicji interfejsu API.

2. Skonfiguruj subskrypcję zdarzeń w centrum interfejsu API platformy Azure, aby wyzwolić aplikację funkcji.

3. Zdarzenie jest wyzwalane przez dodanie lub zastąpienie definicji interfejsu API w centrum interfejsu API.

4. Po otrzymaniu zdarzenia aplikacja funkcji wywołuje aparat lintingu Spectral.

5. Aparat linting sprawdza, czy interfejsy API zdefiniowane w definicji są zgodne z przewodnikiem stylu interfejsu API organizacji i generuje raport.

6. Wyświetl raport analizy w centrum interfejsu API.

Opcje wdrażania aparatu linting i subskrypcji zdarzeń

Ten artykuł zawiera dwie opcje wdrażania aparatu linting i subskrypcji zdarzeń w Centrum interfejsu API:

• Wdrożenie automatyczne — użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd) na potrzeby jednoetapowego wdrożenia infrastruktury linting. Ta opcja jest zalecana w przypadku usprawnionego procesu wdrażania.

• Wdrażanie ręczne — postępuj zgodnie ze wskazówkami krok po kroku, aby wdrożyć aplikację usługi Azure Functions i skonfigurować subskrypcję zdarzeń. Ta opcja jest zalecana, jeśli wolisz ręcznie wdrażać zasoby i zarządzać nimi.

Ograniczenia

• Linting obsługuje obecnie tylko pliki specyfikacji JSON lub YAML, takie jak dokumenty specyfikacji OpenAPI lub AsyncAPI.
• Domyślnie aparat linting używa wbudowanego spectral:oas zestawu reguł. Aby rozszerzyć zestaw reguł lub utworzyć niestandardowe przewodniki stylu interfejsu API, zobacz repozytorium Spectral GitHub.
• Aplikacja funkcji platformy Azure, która wywołuje linting, jest obciążana oddzielnie i zarządzana i konserwowana.

Wymagania wstępne

• Centrum interfejsu API w ramach subskrypcji platformy Azure. Jeśli jeszcze go nie utworzono, zobacz Szybki start: tworzenie centrum interfejsu API.

• Dostawca zasobów usługi Event Grid zarejestrowany 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.

• W przypadku 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.

  Uwaga

  az apic Polecenia wymagają rozszerzenia interfejsu wiersza polecenia platformy apic-extension Azure. Jeśli nie użyto az apic poleceń, rozszerzenie można zainstalować dynamicznie po uruchomieniu pierwszego az apic polecenia lub zainstalować rozszerzenie ręcznie. Dowiedz się więcej o rozszerzeniach interfejsu wiersza polecenia platformy Azure.

  Zapoznaj się z informacjami o wersji, aby uzyskać najnowsze zmiany i aktualizacje w pliku apic-extension.

  Uwaga

  Przykłady poleceń interfejsu wiersza polecenia platformy Azure w tym artykule mogą być uruchamiane w programie PowerShell lub powłoce bash. W razie potrzeby ze względu na różne składnie zmiennych podano oddzielne przykłady poleceń dla dwóch powłok.

azd wdrażanie aplikacji usługi Azure Functions i subskrypcji zdarzeń

Ta sekcja zawiera zautomatyzowane kroki przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure w celu skonfigurowania aplikacji i subskrypcji zdarzeń usługi Azure Functions, która umożliwia linting i analizę w centrum interfejsu API. Zasoby można również skonfigurować ręcznie.

Inne wymagania wstępne dotyczące tej opcji

• Azure Developer CLI (azd)

Uruchamianie przykładu przy użyciu polecenia azd

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.

Ręczne kroki konfigurowania aplikacji i subskrypcji zdarzeń usługi Azure Functions

Ta sekcja zawiera instrukcje ręcznego wdrażania umożliwiające skonfigurowanie subskrypcji aplikacji i zdarzeń usługi Azure Functions w celu włączenia lintingu i analizy w centrum interfejsu API. Do automatycznego wdrażania można również użyć interfejsu wiersza polecenia dla deweloperów platformy Azure.

Inne wymagania wstępne dotyczące tej opcji

• Program Visual Studio Code z rozszerzeniem usługi Azure Functions w wersji 1.10.4 lub nowszej.

Krok 1. Wdrażanie aplikacji usługi Azure Functions

Aby wdrożyć aplikację usługi Azure Functions, która uruchamia funkcję linting w definicjach interfejsu API:

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

2. 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.

3. Opcjonalnie uruchom aplikację funkcji lokalnie, aby ją przetestować. Aby uzyskać szczegółowe informacje, zobacz plik README w repozytorium.

4. Wdróż aplikację funkcji na platformie Azure. Aby uzyskać instrukcje, zobacz Szybki start: tworzenie funkcji na platformie Azure przy użyciu języka TypeScript przy użyciu programu Visual Studio Code.

   Uwaga

   Wdrażanie aplikacji funkcji może potrwać kilka minut.

5. Zaloguj się do witryny Azure Portal i przejdź do aplikacji funkcji.

6. Na stronie Przegląd sprawdź następujące szczegóły:

   • Upewnij się, że stan aplikacji funkcji to Uruchomiono.
   • W obszarze Funkcje upewnij się, że stan funkcji apicenter-analyzer ma wartość Włączone.

   

Krok 2. Konfigurowanie tożsamości zarządzanej w aplikacji funkcji

Aby umożliwić aplikacji funkcji dostęp do centrum interfejsu API, skonfiguruj tożsamość zarządzaną dla aplikacji funkcji. W poniższych krokach pokazano, jak włączyć i skonfigurować tożsamość zarządzaną przypisaną przez system dla aplikacji funkcji przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Portal

1. W witrynie Azure Portal przejdź do aplikacji funkcji i wybierz pozycję Tożsamość w sekcji Ustawienia .
2. Na karcie Przypisane przez system ustaw wartość Stan na Wł., a następnie wybierz pozycję Zapisz.

Teraz, gdy tożsamość zarządzana jest włączona, przypisz jej rolę Menedżera zgodności Centrum interfejsów API platformy Azure, aby uzyskać dostęp do centrum interfejsu API.

1. W witrynie Azure Portal przejdź do centrum interfejsu API i wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
2. Wybierz pozycję + Dodaj > przypisanie roli.
3. Wybierz pozycję Role funkcji zadania, a następnie wybierz pozycję Azure API Center Compliance Manager. Wybierz Dalej.
4. Na stronie Członkowie w obszarze Przypisz dostęp do wybierz pozycję Tożsamość > zarządzana i Wybierz członków.
5. Na stronie Wybieranie tożsamości zarządzanych wyszukaj i wybierz tożsamość zarządzaną aplikacji funkcji. Kliknij pozycję Wybierz , a następnie przycisk Dalej.
6. Przejrzyj przypisanie roli i wybierz pozycję Przejrzyj i przypisz.

Interfejs wiersza polecenia platformy Azure

1. Włącz tożsamość przypisaną przez system aplikacji funkcji przy użyciu polecenia az functionapp identity assign . Zastąp <function-app-name> wartości i <resource-group-name> nazwą aplikacji funkcji i nazwą grupy zasobów. Następujące polecenie przechowuje identyfikator podmiotu zabezpieczeń tożsamości zarządzanej przypisanej przez system w zmiennej principalID .

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. Pobierz identyfikator zasobu centrum interfejsu API. Zastąp <apic-name> element nazwą <resource-group-name> centrum interfejsu API i nazwą grupy zasobów.

   #! /bin/bash
   apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. Przypisz tożsamość zarządzaną aplikacji funkcji rolę Menedżera zgodności centrum interfejsu API platformy Azure w centrum interfejsu API przy użyciu polecenia az role assignment create .

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

Krok 3. Konfigurowanie subskrypcji zdarzeń w centrum interfejsu API

Teraz utwórz subskrypcję zdarzeń w centrum interfejsu API, aby wyzwolić aplikację funkcji po przekazaniu lub zaktualizowaniu pliku definicji interfejsu API. W poniższych krokach pokazano, jak utworzyć subskrypcję zdarzeń przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Portal

1. W witrynie Azure Portal przejdź do centrum interfejsu API i wybierz pozycję Zdarzenia.

2. Na karcie Wprowadzenie wybierz pozycję Funkcja platformy Azure.

3. Na stronie Tworzenie subskrypcji zdarzeń wykonaj następujące czynności:

   1. Wprowadź opisową nazwę subskrypcji zdarzeń i wybierz pozycję Schemat usługi Event Grid.

   2. W obszarze Szczegóły tematu wprowadź wybraną nazwę tematu systemowego.

   3. W obszarze Typy zdarzeń wybierz następujące zdarzenia:

      • Dodano definicję interfejsu API
      • Zaktualizowano definicję interfejsu API

   4. W obszarze Szczegóły punktu końcowego wybierz pozycję Funkcja > platformy Azure Konfiguruj punkt końcowy.

   5. Na stronie Wybieranie funkcji platformy Azure wybierz aplikację funkcji i skonfigurowaną funkcję apicenter-linter. Kliknij pozycję Potwierdź wybór.

   6. Wybierz pozycję Utwórz.

      

4. Wybierz kartę Subskrypcje zdarzeń i wybierz pozycję Odśwież. Upewnij się, że stan aprowizacji subskrypcji zdarzeń to Powodzenie.

   

Interfejs wiersza polecenia platformy Azure

1. Pobierz identyfikator zasobu centrum interfejsu API. Zastąp <apic-name> element nazwą <resource-group-name> centrum interfejsu API i nazwą grupy zasobów.

   #! /bin/bash
   apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

2. Pobierz identyfikator zasobu funkcji w aplikacji funkcji. W tym przykładzie nazwa funkcji to apicenter-analyzer. Zastąp <function-app-name> ciąg i <resource-group-name> nazwą aplikacji funkcji i nazwą grupy zasobów.

   #! /bin/bash
   functionID=$(az functionapp function show --name <function-app-name> \
       --function-name apicenter-analyzer --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $functionID=$(az functionapp function show --name <function-app-name> `
       --function-name apicenter-analyzer --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. Utwórz subskrypcję zdarzeń za pomocą polecenia az eventgrid event-subscription create . Utworzona subskrypcja zawiera zdarzenia służące do dodawania lub aktualizowania definicji interfejsu API.

   #! /bin/bash
   az eventgrid event-subscription create --name MyEventSubscription \
       --source-resource-id "$apicID" --endpoint "$functionID" \
       --endpoint-type azurefunction --included-event-types \
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   # PowerShell syntax
   az eventgrid event-subscription create --name MyEventSubscription `
       --source-resource-id "$apicID" --endpoint "$functionID" `
       --endpoint-type azurefunction --included-event-types `
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   Dane wyjściowe polecenia zawierają szczegóły subskrypcji zdarzeń. Możesz również uzyskać szczegółowe informacje za pomocą polecenia az eventgrid event-subscription show . Na przykład:

   az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"
   

Uwaga

Propagacja subskrypcji zdarzeń do aplikacji funkcji może zająć trochę czasu.

Wyzwalanie zdarzenia w centrum interfejsu API

Aby przetestować subskrypcję zdarzeń, spróbuj przekazać lub zaktualizować plik definicji interfejsu API skojarzony z wersją interfejsu API w centrum interfejsu API. Na przykład przekaż dokument OpenAPI lub AsyncAPI. Po wyzwoleniu subskrypcji zdarzeń aplikacja funkcji wywołuje aparat linting interfejsu API w celu przeanalizowania definicji interfejsu API.

• Aby uzyskać szczegółowe instrukcje dotyczące dodawania interfejsu API, wersji interfejsu API i definicji interfejsu API do centrum interfejsu API, zobacz Samouczek: rejestrowanie interfejsów API w centrum interfejsu API.
• Aby utworzyć interfejs API, przekazując plik definicji interfejsu API przy użyciu interfejsu wiersza polecenia platformy Azure, zobacz Rejestrowanie interfejsu API z pliku specyfikacji.

Aby potwierdzić, że subskrypcja zdarzeń została wyzwolona:

1. Przejdź do centrum interfejsu API i wybierz pozycję Zdarzenia w menu po lewej stronie.

2. Wybierz kartę Subskrypcje zdarzeń i wybierz subskrypcję zdarzeń dla aplikacji funkcji.

3. Przejrzyj metryki, aby potwierdzić, że subskrypcja zdarzeń została wyzwolona i że linting został pomyślnie wywołany.

   

   Uwaga

   Wyświetlenie metryk może potrwać kilka minut.

Po przeanalizowaniu definicji interfejsu API aparat linting generuje raport na podstawie skonfigurowanego przewodnika stylu interfejsu API.

Wyświetlanie raportów analizy interfejsu API

Raport analizy definicji interfejsu API można wyświetlić w witrynie Azure Portal. Po przeanalizowaniu definicji interfejsu API raport wyświetla listę błędów, ostrzeżeń i informacji na podstawie skonfigurowanego przewodnika stylu interfejsu API.

W portalu można również wyświetlić podsumowanie raportów analizy dla wszystkich definicji interfejsu API w centrum interfejsu API.

Raport analizy definicji interfejsu API

Aby wyświetlić raport analizy definicji interfejsu API w centrum interfejsu API:

1. W portalu przejdź do wersji interfejsu API w centrum interfejsu API, w którym dodano lub zaktualizowaliśmy definicję interfejsu API.
2. W menu po lewej stronie w obszarze Szczegóły wybierz pozycję Definicje.
3. Wybierz przekazaną lub zaktualizowaną definicję interfejsu API.
4. Wybierz kartę Analiza .

Zostanie otwarty raport analizy interfejsu API, który wyświetla definicję i błędy interfejsu API, ostrzeżenia i informacje na podstawie skonfigurowanego przewodnika po stylu interfejsu API. Poniższy zrzut ekranu przedstawia przykład raportu analizy interfejsu API.

Podsumowanie analizy interfejsu API

Aby wyświetlić podsumowanie raportów analizy dla wszystkich definicji interfejsu API w centrum interfejsu API:

1. W portalu przejdź do centrum interfejsu API.

2. W menu po lewej stronie w obszarze Ład wybierz pozycję Analiza interfejsu API. Zostanie wyświetlone podsumowanie.

   

Powiązana zawartość

Dowiedz się więcej o usłudze Event Grid:

• Włączanie analizy interfejsu API w centrum interfejsu API — zarządzane przez firmę Microsoft
• Tematy systemowe w usłudze Azure Event Grid
• Dostarczanie wypychane usługi Event Grid — pojęcia
• Schemat usługi Event Grid dla centrum interfejsu API platformy Azure