Aktivieren der API-Analyse in Ihrem API Center – selbstverwaltet

In diesem Artikel wird erläutert, wie Sie die API-Analyse im Azure API Center aktivieren, indem Sie eine Linting-Engine und Trigger manuell einrichten. Die API-Analyse bietet Linting-Funktionen zum Analysieren von API-Definitionen im API Center Ihrer Organisation. Linting stellt sicher, dass Ihre API-Definitionen den Regeln des Organisationsstils entsprechen und sowohl einzelne als auch Zusammenfassungsberichte generieren. Verwenden Sie die API-Analyse, um häufige Fehler und Inkonsistenzen in Ihren API-Definitionen zu erkennen.

Hinweis

In der Vorschau kann das Azure API Center auch automatisch eine Linting-Engine und alle erforderlichen Abhängigkeiten und Trigger einrichten. Weitere Informationen

Übersicht über das Szenario

In diesem Szenario analysieren Sie API-Definitionen in Ihrem API Center mithilfe der Open-Source-Linting-Engine Spectral. Eine Azure Functions-App führt die Linting-Engine als Reaktion auf Ereignisse in Ihrem API Center aus. Spektralprüfungen, dass die in einem JSON- oder YAML-Spezifikationsdokument definierten APIs den Regeln in einem anpassbaren API-Stilleitfaden entsprechen. Es wird ein Analysebericht generiert, den Sie in Ihrem API Center anzeigen können.

Das folgende Diagramm zeigt die Schritte zum Aktivieren von Linten und Analyse im API Center.

1. Sie stellen eine Azure Functions-App bereit, die die Spektral-Linting-Engine auf einer API-Definition ausführt.

2. Sie konfigurieren ein Ereignisabonnement in einem Azure API Center, um die Funktions-App auszulösen.

3. Ein Ereignis wird ausgelöst, indem eine API-Definition im API Center hinzugefügt oder ersetzt wird.

4. Beim Empfangen des Ereignisses ruft die Funktions-App die Spektral-Linting-Engine auf.

5. Die Linting-Engine überprüft, ob die in der Definition definierten APIs dem API-Stilleitfaden der Organisation entsprechen und einen Bericht generiert.

6. Sie zeigen den Analysebericht im API Center an.

Optionen zum Bereitstellen der Linting-Engine und des Ereignisabonnements

In diesem Artikel werden zwei Möglichkeiten zum Bereitstellen der Linting-Engine und des Ereignisabonnements im API Center beschrieben:

• Automatisierte Bereitstellung: Verwenden Sie die Azure Developer CLI (azd) für die Bereitstellung der Lintinginfrastruktur in einem Schritt. Diese Option wird für einen optimierten Bereitstellungsprozess empfohlen.

• Manuelle Bereitstellung: Befolgen Sie den ausführlichen Leitfaden zum Bereitstellen der Azure Functions-App und Konfigurieren des Ereignisabonnements. Diese Option wird empfohlen, wenn Sie die Ressourcen lieber manuell bereitstellen und verwalten möchten.

Begrenzungen

• Linten unterstützt derzeit nur JSON- oder YAML-Spezifikationsdateien, z. B. OpenAPI- oder AsyncAPI-Spezifikationsdokumente.
• Standardmäßig verwendet die Linting-Engine das integrierte spectral:oas Regelset. Informationen zum Erweitern des Regelsets oder Erstellen von benutzerdefinierten API-Stilleitfaden finden Sie im Spektral-GitHub-Repository.
• Die Azure-Funktions-App, die Linting aufruft, wird separat berechnet und Sie verwalten und warten sie.

Voraussetzungen

• Ein API-Center in Ihrem Azure-Abonnement. Wenn Sie noch keins erstellt haben, lesen Sie die Schnellstartanleitung: Erstellen Ihres API-Centers.

• Der Event Grid-Ressourcenanbieter, der in Ihrem Abonnement registriert ist. Wenn Sie den Event Grid-Ressourcenanbieter registrieren müssen, lesen Sie Abonnieren von Ereignissen, die von einem Partner mit Azure Event Grid veröffentlicht wurden.

• Für die Azure CLI:

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

    

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

  Hinweis

  Für az apic-Befehle wird die Azure CLI-Erweiterung apic-extension benötigt. Wenn Sie keine az apic-Befehle verwendet haben, kann die Erweiterung dynamisch installiert werden, wenn Sie den ersten az apic-Befehl ausführen. Sie können die Erweiterung auch manuell installieren. Hier finden Si weitere Informationen zu Azure CLI-Erweiterungen.

  In den Versionshinweisen finden Sie die neuesten Änderungen und Updates in der apic-extension.

  Hinweis

  Azure CLI-Befehlsbeispiele in diesem Artikel können in PowerShell oder einer Bash-Shell ausgeführt werden. Bei Bedarf aufgrund unterschiedlicher Variablensyntax werden separate Befehlsbeispiele für die beiden Shells bereitgestellt.

azd-Bereitstellung der Azure Functions-App und des Ereignisabonnements

Dieser Abschnitt enthält automatisierte Schritte in der Azure Developer CLI zum Konfigurieren der Azure Functions-App und des Ereignisabonnements, die das Linting und die Analyse in Ihrem API Center ermöglichen. Sie können die Ressourcen auch manuellkonfigurieren.

Weitere Voraussetzungen für diese Option

• Azure Developer CLI (azd)

Ausführen des Beispiels mithilfe von azd

1. Klonen Sie das GitHub-Repository und öffnen Sie es in Visual Studio Code.

2. Wechseln Sie in das Verzeichnis APICenter-Analyzer im Repository.

3. Im Ordner resources/rulesets finden Sie eine Datei oas.yaml. Diese Datei spiegelt Ihren aktuellen API-Stilleitfaden wider und kann basierend auf Ihren Organisationsanforderungen und -anforderungen geändert werden.

4. Authentifizieren Sie sich mithilfe der folgenden Befehle bei der Azure Developer CLI und der Azure-Befehlszeilenschnittstelle:

   azd auth login
   
   az login
   

5. Führen Sie den folgenden Befehl aus, um die Lintinginfrastruktur in Ihrem Azure-Abonnement bereitzustellen.

   azd up
   

6. Befolgen Sie die Anweisungen, um die erforderlichen Bereitstellungsinformationen und -einstellungen anzugeben, z. B. den Namen der Umgebung und den API Center-Namen. Ausführliche Informationen finden Sie unter Ausführen des Beispiels mithilfe der Azure Developer CLI (azd).

   Hinweis

   Die Bereitstellung kann einige Minuten dauern.

7. Navigieren Sie nach Abschluss der Bereitstellung im Azure-Portal zum API Center. Wählen Sie im linken Menü Ereignisse>Ereignisabonnementsaus, um das erstellte Ereignisabonnement anzuzeigen.

Sie können jetzt eine API-Definitionsdatei in Ihr API Center hochladen, um das Ereignisabonnement auszulösen und die Linting-Engine auszuführen.

Manuelle Schritte zum Konfigurieren der Azure Functions-App und des Ereignisabonnements

In diesem Abschnitt finden Sie die Schritte zur manuellen Bereitstellung zum Konfigurieren der Azure Functions-App und des Ereignisabonnements und zum Aktivieren von Linting und Analyse in Ihrem API Center. Sie können auch die Azure Developer CLI für die automatisierte Bereitstellung verwenden.

Weitere Voraussetzungen für diese Option

• Visual Studio Code mit der Azure Funktionserweiterung v1.10.4 oder höher.

Schritt 1. Bereitstellen in Ihrer Azure Funktions-App

Stellen Sie die Azure Funktions-App bereit, die die Lintingfunktion in API-Definitionen ausführt:

1. Klonen Sie das GitHub-Repository und öffnen Sie es in Visual Studio Code.

2. Im Ordner resources/rulesets finden Sie eine Datei oas.yaml. Diese Datei spiegelt Ihren aktuellen API-Stilleitfaden wider und kann basierend auf Ihren Organisationsanforderungen und -anforderungen geändert werden.

3. Führen Sie optional die Funktions-App lokal aus, um sie zu testen. Ausführliche Informationen finden Sie in der README-Datei im Repository.

4. Stellen Sie die Funktions-App in Azure bereit. Die Schritte finden Sie in der Schnellstartanleitung: Erstellen einer Funktion in Azure mit TypeScript mit Visual Studio Code.

   Hinweis

   Die Bereitstellung der Funktions-App kann einige Minuten dauern.

5. Melden Sie sich beim Azure-Portal an, und navigieren Sie zur Funktions-App.

6. Überprüfen Sie auf der Seite Übersicht die folgenden Details:

   • Vergewissern Sie sich, dass der Status der Funktions-App ausgeführt wird.
   • Vergewissern Sie sich unter Funktionen, dass der Status der Apicenter-Analyzer-Funktion aktiviert ist.

   

Schritt 2. Konfigurieren der verwalteten Identität in Ihrer Funktions-App

Um die Funktions-App für den Zugriff auf das API Center zu aktivieren, konfigurieren Sie eine verwaltete Identität für die Funktions-App. Die folgenden Schritte zeigen, wie Sie eine vom System zugewiesene verwaltete Identität für die Funktions-App mithilfe des Azure-Portals oder der Azure CLI aktivieren und konfigurieren.

Portal

1. Navigieren Sie im Azure-Portal zu Ihrer Funktions-App, und wählen Sie im Abschnitt Einstellungen die Option Identität aus.
2. Stellen Sie auf der Registerkarte System zugewiesen den Status auf Ein und wählen Sie dann Speichern.

Nachdem die verwaltete Identität aktiviert ist, weisen Sie sie der Azure API Center Compliance Manager-Rolle zu, um auf das API Center zuzugreifen.

1. Navigieren Sie im Azure-Portal zu Ihrem API Center, und wählen Sie Zugriffssteuerung (IAM) aus.
2. Wählen Sie + Hinzufügen > Rollenzuweisung hinzufügen.
3. Wählen Sie Rollen der Auftragsfunktion und dann Azure API Center Compliance Manager aus. Wählen Sie Weiter aus.
4. Wählen Sie auf der Seite Mitglieder unter Zugriff zuweisen die Option Verwaltete Identität> + Mitglieder auswählen aus.
5. Suchen Sie auf der Seite Verwaltete Identitäten auswählen nach der verwalteten Identität der Funktions-App, und wählen Sie sie aus. Wählen Sie Auswählen und dann Weiter aus.
6. Überprüfen Sie die Rollenzuweisung, und wählen Sie Überprüfen + zuweisen aus.

Azure-Befehlszeilenschnittstelle

1. Aktivieren Sie die vom System zugewiesene Identität der Funktions-App mithilfe des Befehls az functionapp identity assign. Ersetzen Sie <function-app-name> und <resource-group-name> durch Ihre Funktions-App und den Ressourcengruppennamen. Der folgende Befehl speichert die Prinzipal-ID der vom System zugewiesenen verwalteten Identität in der principalID-Variablen.

   #! /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. Rufen Sie die Ressourcen-ID Ihres API Centers ab. Ersetzen Sie <apic-name> und <resource-group-name> durch Ihren API-Center-Namen und den Ressourcengruppennamen.

   #! /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. Weisen Sie die verwaltete Identität der Funktions-App der Rolle „Azure API Center Compliance Manager“ im API Center mithilfe des az Rollenzuweisung-Befehls.

   #! /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 
   

Schritt 3. Konfigurieren des Ereignisabonnements im API Center

Erstellen Sie nun ein Ereignisabonnement im API Center, um die Funktions-App auszulösen, wenn eine API-Definitionsdatei hochgeladen oder aktualisiert wird. Die folgenden Schritte zeigen, wie Sie das Ereignisabonnement mithilfe des Azure-Portals oder der Azure CLI erstellen.

Portal

1. Navigieren Sie im Azure-Portal zum API Center, und wählen Sie Ereignisse aus.

2. Wählen Sie auf der Registerkarte Erste Schritte Azure Function aus.

3. Führen Sie auf der Seite Ereignisabonnement erstellen die folgenden Schritte aus:

   1. Geben Sie einen beschreibenden Namen für das Ereignisabonnement ein, und wählen Sie Event Grid-Schema aus.

   2. Geben Sie in den Themendetails einen Systemthemennamen Ihrer Wahl ein.

   3. Wählen Sie in Ereignistypen die folgenden Ereignisse aus:

      • API-Definition hinzugefügt
      • API-Definition aktualisiert

   4. Wählen Sie unter Endpunktdetails die Option Azure-Funktion >Einen Endpunkt konfigurieren aus.

   5. Wählen Sie auf der Seite Azure-Funktion auswählen die Funktions-App und die apicenter-linter-Funktion aus, die Sie konfiguriert haben. Klicken Sie auf Auswahl bestätigen.

   6. Klicken Sie auf Erstellen.

      

4. Wählen Sie die Registerkarte Ereignisabonnements und dann Aktualisieren aus. Vergewissern Sie sich, dass der Bereitstellungsstatus des Ereignisabonnements erfolgreich ist.

   

Azure-Befehlszeilenschnittstelle

1. Rufen Sie die Ressourcen-ID Ihres API Centers ab. Ersetzen Sie <apic-name> und <resource-group-name> durch Ihren API-Center-Namen und den Ressourcengruppennamen.

   #! /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. Rufen Sie die Ressourcen-ID der Funktion in der Funktions-App ab. In diesem Beispiel ist der Funktionsname apicenter-analyzer. Ersetzen Sie <function-app-name> und <resource-group-name> durch Ihre Funktions-App und den Ressourcengruppennamen.

   #! /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. Erstellen Sie ein Ereignisabonnement mithilfe des Befehls az eventgrid event-Abonnement erstellen. Das erstellte Abonnement enthält Ereignisse zum Hinzufügen oder Aktualisieren von API-Definitionen.

   #! /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
   

   Die Befehlsausgabe zeigt Details des Ereignisabonnements an. Sie können auch Details über den Befehl az eventgrid event-Abonnement anzeigen abrufen. Zum Beispiel:

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

Hinweis

Es kann eine kurze Zeit dauern, bis das Ereignisabonnement an die Funktions-App weitergegeben wird.

Auslösen eines Ereignisses in Ihrem API Center

Um das Ereignisabonnement zu testen, versuchen Sie, eine API-Definitionsdatei hochzuladen oder zu aktualisieren, die einer API-Version im API Center zugeordnet ist. Laden Sie beispielsweise ein OpenAPI- oder AsyncAPI-Dokument hoch. Nachdem das Ereignisabonnement ausgelöst wurde, ruft die Funktions-App die API-Linting-Engine auf, um die API-Definition zu analysieren.

• Ausführliche Schritte zum Hinzufügen einer API, API-Version und API-Definition zum API Center finden Sie im Lernprogramm: Registrieren von APIs im API Center.
• Informationen zum Erstellen einer API durch Hochladen einer API-Definitionsdatei mithilfe der Azure CLI finden Sie unter Registrieren der API aus einer Spezifikationsdatei.

So bestätigen Sie, dass das Ereignisabonnement ausgelöst wurde:

1. Navigieren Sie zum API Center, und wählen Sie im linken Menu Ereignisse aus.

2. Wählen Sie die Registerkarte Ereignisabonnements und dann das Ereignisabonnement für Ihre Funktions-App aus.

3. Überprüfen Sie die Metriken, um zu bestätigen, dass das Ereignisabonnement ausgelöst und dass das Linten erfolgreich aufgerufen wurde.

   

   Hinweis

   Es kann einige Minuten dauern, bis die Metriken angezeigt werden.

Nach der Analyse der API-Definition generiert die Linting-Engine einen Bericht basierend auf dem konfigurierten API-Stilleitfaden.

Anzeigen von API-Analyseberichten

Sie können den Analysebericht für Ihre API-Definition im Azure-Portal anzeigen. Nachdem eine API-Definition analysiert wurde, listet der Bericht Fehler, Warnungen und Informationen basierend auf dem konfigurierten API-Stilleitfaden auf.

Im Portal können Sie auch eine Zusammenfassung der Analyseberichte für alle API-Definitionen im API Center anzeigen.

Analysebericht für eine API-Definition

So zeigen Sie den Analysebericht für eine API-Definition im API-Center an:

1. Navigieren Sie im Portal zu der API-Version im API Center, in der Sie eine API-Definition hinzugefügt oder aktualisiert haben.
2. Wählen Sie im linken Menü unter Details die Option Definitionen aus.
3. Wählen Sie die API-Definition aus, die Sie hochgeladen oder aktualisiert haben.
4. Wählen Sie die Registerkarte Analyse aus.

Der API-Analysebericht wird geöffnet, und er zeigt die API-Definition und Fehler, Warnungen und Informationen basierend auf dem konfigurierten API-Stilleitfaden an. Der folgende Screenshot zeigt ein Beispiel für einen API-Analysebericht.

Zusammenfassung der API-Analyse

So zeigen Sie eine Zusammenfassung der Analyseberichte für alle API-Definitionen im API-Center an:

1. Navigieren Sie im Portal zu Ihrem API-Center.

2. Wählen Sie im linken Menü unter Governance die Opiton API-Analyse aus. Die Zusammenfassung wird angezeigt.

   

Zugehöriger Inhalt

Erfahren Sie mehr über Event Grid:

• Aktivieren der API-Analyse in Ihrem API Center – von Microsoft verwaltet
• Systemthemen in Azure Event Grid
• Event Grid Pushübermittlungskonzepte
• Event Grid-Schema für das Azure API Center