Freigeben über

Aktivieren von Linten und Analyse für API-Governance in Ihrem API Center

  • Artikel

In diesem Artikel wird gezeigt, wie Sie das Linten zum Analysieren von API-Definitionen im API Center Ihrer Organisation für die Einhaltung der API-Stilregeln Ihrer Organisation aktivieren. Linten generiert einen Analysebericht, auf den Sie im API Center zugreifen können. Verwenden Sie API-Linten und -Analyse, um häufige Fehler und Inkonsistenzen in Ihren API-Definitionen zu erkennen.

Ü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 Bericht zur API-Compliance 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.

Diagramm, das zeigt, wie API-Linting im Azure API Center funktioniert.

  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

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

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.

    Screenshot der Funktions-App im Portal.

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.

  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.

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.

  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.

      Screenshot des Erstellens des Ereignisabonnements im Portal.

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

    Screenshot des Status des Ereignisabonnements im Portal.

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.

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.

    Screenshot der Metriken für das Ereignisabonnement im Portal.

    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. Screenshot der Registerkarte „Analyse“ für die API-Definition im Portal.

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.

Screenshot eines API-Analyseberichts im Portal.

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.

    Screenshot der API-Analysezusammenfassung im Portal.

Zugehöriger Inhalt

Erfahren Sie mehr über Event Grid: