Aktivieren der API-Analyse in Ihrem API Center – von Microsoft verwaltet

  • Artikel

In diesem Artikel wird erläutert, wie Sie die API-Analyse im Azure API Center aktivieren, ohne sie selbst verwalten zu müssen (Vorschau). 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.

Wichtig

Die Analyse der verwalteten API in API Center richtet automatisch eine Linting-Engine und die erforderlichen Abhängigkeiten ein. Sie können Linten und Analyse auch manuell mithilfe einer benutzerdefinierten Azure-Funktion aktivieren. Deaktivieren Sie alle Funktionen, die für manuelles Linten verwendet werden, bevor Sie die Analyse der verwalteten API aktivieren.

Szenario:

  1. Fügen Sie ihrem API Center mithilfe der Visual Studio Code-Erweiterung für Azure API Center einen Linting-Regelsatz (API-Styleguide) hinzu.
  2. Das Azure API Center führt automatisch das Linten aus, wenn Sie eine API-Definition hinzufügen oder aktualisieren. Es wird auch für alle API-Definitionen ausgelöst, wenn Sie einen Regelsatz im API Center bereitstellen.
  3. Überprüfen Sie API-Analyseberichte im Azure-Portal, um zu sehen, wie Ihre API-Definitionen dem Styleguide entsprechen.
  4. Passen Sie optional den Regelsatz für die APIs Ihrer Organisation an. Testen Sie den benutzerdefinierten Regelsatz lokal, bevor Sie ihn in Ihrem API Center bereitstellen.

Begrenzungen

  • Derzeit werden nur OpenAPI-Spezifikationsdokumente im JSON- oder YAML-Format analysiert.
  • Standardmäßig aktivieren Sie die Analyse mit dem spectral:oas Regelsatz. Weitere Informationen zu den integrierten Regeln finden Sie im Spectral-GitHub-Repository.
  • Derzeit konfigurieren Sie einen einzelnen Regelsatz, der dann auf alle OpenAPI-Definitionen im API Center angewendet wird.
  • Es gibt Einschränkungen für die maximale Anzahl analysierter API-Definitionen. Der Abschluss der Analyse kann einige Minuten bis zu 24 Stunden dauern.

Voraussetzungen

Aktivieren von API-Analysen mit Visual Studio Code

So aktivieren Sie API-Analysen mithilfe des standardmäßigen Linting-Regelsatzes:

  1. Öffnen Sie in Visual Studio Code einen Ordner, den Sie zum Verwalten von Regelsätzen für Azure API Center verwenden möchten.

  2. Wählen Sie in der Aktivitätsleiste das Symbol „Azure API Center“ aus.

  3. Erweitern Sie im Bereich „API Center“ die API Center-Ressource, in der die API-Analyse aktiviert werden soll.

  4. Klicken Sie mit der rechten Maustaste auf Regeln, und wählen Sie API-Analyse aktivieren aus.

    Screenshot: Aktivierung von API-Linten und -Analyse in Visual Studio Code

Sie werden durch eine Meldung benachrichtigt, wenn die API-Analyse erfolgreich aktiviert wurde. Im Stammverzeichnis Ihres Arbeitsordners wird ein Ordner für Ihr API-Center in .api-center-rules erstellt. Der Ordner für Ihr API Center enthält Folgendes:

  • Eine ruleset.yml-Datei, die den standardmäßigen API-Styleguide definiert, der vom Linting-Modul verwendet wird.
  • Ein Ordner functions mit einer benutzerdefinierten Beispielfunktion, die Sie zum Erweitern des Regelsatzes verwenden können.

Bei aktivierter Analyse analysiert das Linting-Modul anhand des Standardregelsatzes API-Definitionen im API Center und generiert API-Analyseberichte.

Anzeigen von API-Analyseberichten

Zeigen Sie eine Analysezusammenfassung und die Analyseberichte für Ihre API-Definitionen im Azure-Portal an. Nach der Analyse der API-Definitionen werden in den Berichten Fehler, Warnungen und Informationen basierend auf dem konfigurierten API-Styleguide aufgelistet.

So zeigen Sie eine Analysezusammenfassung 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.

  3. Wählen Sie optional das Symbol „API-Analysebericht“ für eine API-Definition aus. Der API-Analysebericht der Definition wird angezeigt, wie im folgenden Screenshot dargestellt.

    Screenshot eines API-Analyseberichts im Portal.

    Tipp

    Sie können den API-Analysebericht auch anzeigen, indem Sie in der Menüleiste der API-Definition Analyse auswählen.

Anpassen des Regelsatzes

Sie können den Standardregelsatz anpassen oder als API-Styleguide Ihrer Organisation ersetzen. Sie können z. B. den Regelsatz erweitern oder benutzerdefinierte Funktionen hinzufügen.

So passen Sie den Regelsatz an oder ersetzen Sie ihn:

  1. Öffnen Sie in Visual Studio Code den Ordner .api-center-rules im Stammverzeichnis Ihres Arbeitsordners.
  2. Öffnen Sie die Datei ruleset.yml im Ordner der API Center-Ressource.
  3. Ändern oder ersetzen Sie den Inhalt nach Bedarf.
  4. Speichern Sie Ihre Änderungen an ruleset.yml.

Lokales Testen des Regelsatzes

Bevor Sie den benutzerdefinierte Regelsatz im API Center bereitstellen, überprüfen Sie es lokal. Die Azure API Center-Erweiterung für Visual Studio Code bietet integrierte Unterstützung für das Linten von API-Spezifikationen mit Spectral.

  1. Verwenden Sie in Visual Studio Code die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen.

  2. Geben Sie Azure API Center: Set active API Style Guide ein, und drücken Sie die Eingabetaste.

  3. Wählen Sie Lokale Datei auswählen aus, und geben Sie die von Ihnen angepasste Datei ruleset.yml an. Drücken Sie die Eingabetaste.

    In diesem Schritt wird der benutzerdefinierte Regelsatz als aktiver API-Styleguide für das Linten festgelegt.

Wenn Sie nun eine OpenAPI-basierte API-Definitionsdatei öffnen, wird automatisch ein lokaler Linting-Vorgang in Visual Studio Code ausgelöst. Die Ergebnisse werden inline im Editor und im Fenster Probleme (Ansicht > Probleme oder STRG+UMSCHALT+M ) angezeigt.

Screenshot: Linten einer API-Definition in Visual Studio Code

Überprüfen Sie die Ergebnisse des Lintens. Nehmen Sie alle erforderlichen Anpassungen am Regelsatz vor, und testen Sie ihn weiter lokal, bis er das gewünschte Verhalten aufweist.

Bereitstellen des Regelsatzes im API Center

So stellen Sie den benutzerdefinierten Regelsatz im Ihrem API Center bereit:

  1. Wählen Sie auf der Aktivitätsleiste in Visual Studio Code das Symbol „Azure API Center“ aus.
  2. Erweitern Sie im Bereich „API Center“ die API Center-Ressource, in der Sie den Regelsatz angepasst haben.
  3. Klicken Sie mit der rechten Maustaste auf Regeln, und wählen Sie Regeln im API Center bereitstellen aus.

Nachdem die Regeln erfolgreich im API Center bereitgestellt worden sind, werden Sie durch eine Meldung benachrichtigt. Das Linting-Modul verwendet den aktualisierten Regelsatz zum Analysieren von API-Definitionen.

Um die Ergebnisse des Lintens mit dem aktualisierten Regelsatz einzusehen, zeigen Sie die API-Analyseberichte im Portal an.

Zugehöriger Inhalt