Analysieren von APIs im API Center – von Microsoft verwaltet

Das API Center Ihrer Organisation umfasst integrierte, von Microsoft verwaltete Lintenfunktionen (Vorschau), um API-Definitionen für die Einhaltung von Stilregeln Ihrer Organisation zu analysieren und sowohl einzelne als auch zusammenfassende Berichte zu generieren. Die API-Analyse identifiziert häufige Fehler und Inkonsistenzen in Ihren API-Definitionen und hilft diese zu korrigieren.

Mit API-Analyse:

  • Das Azure API Center analysiert Ihre API-Definitionen automatisch, wenn Sie eine API-Definition hinzufügen oder aktualisieren. Die Linting für Ihre API-Definitionen erfolgt standardmäßig mit einem spectral:oas Regelsatz (API-Stilhandbuch).
  • API-Analyseberichte werden im Azure-Portal generiert und zeigen, inwiefern Ihre API-Definitionen dem Styleguide entsprechen.
  • Verwenden Sie Analyseprofile, um die Regeln und Filterbedingungen für die zu analysierenden APIs anzugeben. Passen Sie das Regelet eines Profils mithilfe der Azure API Center-Erweiterung für Visual Studio Code an.

Wichtig

Wenn es Ihnen lieber ist, können Sie selbstverwaltete Linten- und Analysefunktionen mithilfe einer benutzerdefinierten Azure-Funktion aktivieren und die integrierten Funktionen außer Kraft setzen. Deaktivieren Sie alle Funktionen, die für selbstverwaltete Linten verwendet werden, bevor Sie die Analyse der verwalteten API verwenden.

Einschränkungen

  • Derzeit werden nur OpenAPI- und AsyncAPI-Spezifikationsdokumente im JSON- oder YAML-Format analysiert.
  • Es gibt Grenzwerte für die Anzahl der Analyseprofile und die maximale Anzahl analysierter API-Definitionen. Der Abschluss der Analyse kann einige Minuten bis zu 24 Stunden dauern.

Voraussetzungen

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.

Überprüfen Sie im API-Analysebericht auch das für die Analyse verwendete Ruleset und den Verlauf der Lintendurchläufe.

So rufen Sie eine Analysezusammenfassung in der API-Zentrale ab:

  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.

Verwalten von Analyseprofilen

Azure API Center verwendet analyseprofile zum Linting und Analysieren von APIs. Ein Analyseprofil gibt ein Regelsatz an und filtert optional Bedingungen für APIs, die analysiert werden. Das Standardanalyseprofil wendet das spectral:oas Ruleset auf alle OpenAPI- und AsyncAPI-Definitionen an.

Sie können das Regelsatz anpassen und Filterbedingungen im Standardprofil definieren oder ein neues Profil erstellen. Sie können z. B. ein Profil für APIs verwenden, die sich in der Entwicklung befinden, und eine andere für APIs, die sich in der Produktion befinden.

Hinweis

Im Standardplan des API Center können Sie bis zu drei Analyseprofile erstellen. Im kostenlosen Plan wird nur ein einzelnes Profil unterstützt.

So erstellen Sie ein Analyseprofil:

  1. Navigieren Sie im Azure-Portal zum API Center.
  2. Wählen Sie im linken Menü unter "Governance" die Option "API Analysis>Manage analysis profiles>+ Create analysis profile" aus.
  3. Geben Sie im Bereich " Neues Analyseprofil erstellen" einen Namen und eine Beschreibung für das Profil ein.
  4. In Ruleset wird der Analysetyp (Linting-Modul) für das Ruleset angezeigt. Derzeit wird nur Spektral unterstützt.
  5. Fügen Sie unter "Filterbedingungen definieren" eine oder mehrere Filterbedingungen für API-Definitionen hinzu, auf die das Profil angewendet wird.
  6. Wählen Sie Erstellen aus.

Screenshot des Erstellens eines Analyseprofils im Portal.

Das Profil wird erstellt und ein Regelsatzgerüst wird erstellt. Um das aktuelle Regelset anzuzeigen, wählen Sie das Profil aus, und wählen Sie im Kontextmenü (...) die Option " Regelsatz anzeigen" aus.

Um das Regelset anzupassen, fahren Sie mit den folgenden Abschnitten fort.

Das Regelwerk des Profils anpassen

Verwenden Sie die Visual Studio Code-Erweiterung für Azure API Center, um das Regelset eines Profils anzupassen. Nachdem Sie das Regelet angepasst und lokal getestet haben, können Sie es wieder in Ihrem API Center bereitstellen.

  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, an der Sie arbeiten, und erweitern Sie Profile.
  3. Erweitern Sie das Profil, das Sie ändern möchten, und wählen Sie dann aus ruleset.yaml.
  4. Ändern oder ersetzen Sie den Inhalt nach Bedarf.
  5. Speichern Sie Ihre Änderungen an ruleset.yaml.

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.yaml an. Drücken Sie die Eingabetaste.

    In diesem Schritt wird das benutzerdefinierte Regelset als Leitfaden für die aktive API-Formatvorlage für lokale Lintings 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.

Tipp

API-Entwickler in Ihrer Organisation können diese lokale Lintenfunktion auch verwenden, um ihre API-Definitionen zu verbessern, bevor APIs im API Center registriert werden.

Screenshot des Lintens 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.

Regelsatz im API Center bereitstellen

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. Profile erweitern.
  4. Klicken Sie mit der rechten Maustaste auf das Profil, in dem Sie das Regelset angepasst haben, 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 Lintingmodul verwendet das aktualisierte Regelset, um API-Definitionen im Profil zu analysieren.

Um die Ergebnisse der Lint-Überprüfung mit dem aktualisierten Regelsatz einzusehen, sehen Sie sich die API-Analyseberichte im Portal an.

Zugehöriger Inhalt

  • Last updated on