Freigeben über

Analysieren von APIs im API Center – von Microsoft verwaltet

  • Artikel

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. API-Definitionen werden standardmäßig mit einem spectral:oas ruleset (API-Styleguide) gelindert.
  • API-Analyseberichte werden im Azure-Portal generiert und zeigen, inwiefern Ihre API-Definitionen dem Styleguide entsprechen.
  • Sie können die Azure API Center-Erweiterung für Visual Studio Code verwenden, um Ihre eigene API-Styleguides lokal anzupassen und zu testen und dann im API Center bereitzustellen.

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

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 Ruleset, das für die Analyse und den Verlauf von Lintendurchläufen verwendet wurde.

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 die Azure API Center-Erweiterung für Visual Studio Code verwenden, um das Standardruleset für Ihr API Center anzupassen oder als API-Styleguide Ihrer Organisation zu 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. Wählen Sie auf der Aktivitätsleiste in Visual Studio Code das Symbol „Azure API Center“ aus.
  2. Öffnen Sie den .api-center-rules-Ordner im Stammverzeichnis Ihres Arbeitsordners.
  3. Öffnen Sie die Datei „ruleset.yml“ im Ordner Ihrer API Center-Ressource.
  4. Ändern oder ersetzen Sie den Inhalt nach Bedarf.
  5. 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.

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: 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