Freigeben über

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, um ein Lintingmodul und Trigger einzurichten. Diese Funktionen analysieren Ihre API-Definitionen zur Einhaltung von Regeln des Organisationsstils und generieren einzelne und zusammenfassende Berichte. Die API-Analyse hilft dabei, häufige Fehler und Inkonsistenzen in Ihren API-Definitionen zu erkennen.

Die folgenden Verfahren unterstützen die automatisierte Bereitstellung der Linting-Engine und des Ereignisabonnements in Ihrem API-Zentrum. Verwenden Sie die Azure Developer CLI (azd) für die bereitstellung der Lintinginfrastruktur in einem Schritt für einen optimierten Bereitstellungsprozess. Die Azure CLI Befehlsbeispiele können in PowerShell oder einer Bash-Shell ausgeführt werden. Bei Bedarf werden separate Befehlsbeispiele bereitgestellt.

Wenn Sie das Modul und die Ressourcen lieber über manual deployment einrichten möchten, lesen Sie das Azure API Center Analyzer GitHub Repository, um Anleitungen zur Bereitstellung der Funktions-App und zum Konfigurieren des Ereignisabonnements zu erhalten.

Hinweis

Azure API Center konfiguriert automatisch eine Standard-Linting-Engine sowie die Abhängigkeiten für die API-Analyse. Wenn Sie selbstverwaltete Analysen aktivieren, wie in diesem Artikel beschrieben, überschreiben Sie diese integrierten Features.

Übersicht über das Szenario

In diesem Szenario analysieren Sie API-Definitionen im API Center mithilfe des Spectral open source Lintingmoduls. Eine Funktions-App, die mit Azure Functions erstellt wurde, führt das Lintingmodul als Reaktion auf Ereignisse im API Center aus. Spectral prüft, ob die in einem JSON- oder YAML-Spezifikationsdokument definierten APIs den Regeln in einer anpassbaren API-Stilrichtlinie 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.

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

  1. Stellen Sie eine Funktions-App bereit, die das Spectral-Linting-Modul auf eine API-Definition anwendet.

  2. Konfigurieren Sie ein Ereignisabonnement in einem Azure API Center, das die Funktions-App auslöst.

  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. Zeigen Sie den Analysebericht im API-Zentrum an.

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 Regelsatzes oder Erstellen von benutzerdefinierten API-Formatvorlagen finden Sie im Spectral-Repository auf GitHub.

  • Die Funktions-App, die Linting aufruft, wird separat berechnet, und Sie sind für ihre Verwaltung und Wartung zuständig.

Voraussetzungen

Verwenden Sie die azd-Bereitstellung für die Function-App und das Event-Abonnement

Die folgenden Verfahren stellen automatisierte Schritte für die Azure Developer CLI (azd) bereit, um die Funktions-App und das Ereignisabonnement zu konfigurieren, die Linting und Analyse in Ihrem API Center ermöglichen.

Hinweis

Wenn Sie das Modul und die Ressourcen lieber mit manual deployment einrichten möchten, lesen Sie den Azure API Center Analyzer GitHub Repository, um Anleitungen zur Bereitstellung der Funktions-App und zum Konfigurieren des Ereignisabonnements zu erhalten.

Ausführen des Beispiels mithilfe von azd

  1. Klonen Sie das Beispiel Azure API Center Analyzer GitHub Repository auf Ihrem lokalen Computer.

  2. Starten Sie Visual Studio Code, und wählen Sie File>Open Folder (Ctrl+K aus, Ctrl+O). Navigieren Sie zum APICenter-Analyzer Ordner für das geklonte Repository, und wählen Sie "Ordner auswählen" aus.

  3. Visual Studio Code Activity Bar wählen Sie Explorer (Ctrl+Shift+E) aus, damit Sie die Repositoryordnerstruktur anzeigen können.

    • Erweitern Sie den resources/rulesets Ordner, und beachten Sie die oas.yaml Datei. Diese Datei spiegelt Ihr aktuelles API-Stilhandbuch wider. Sie können diese Datei ändern, um Ihre Organisationsanforderungen zu erfüllen.

    • Erweitern Sie den src/functions Ordner, und beachten Sie die ApiAnalyzerFunction.ts Datei. Diese Datei stellt den Funktionscode für die Funktions-App bereit. Sie können diese Datei ändern, um das Funktionsverhalten an Ihre Anwendungsanforderungen anzupassen.

  4. Öffnen Sie ein Terminal in Visual Studio Code, und authentifizieren Sie sich bei der Azure Developer CLI (azd):

    azd auth login

    Tipp

    Sie können Authentifizierungsprobleme in Entwicklungsumgebungen vermeiden, indem Sie die folgenden Befehle ausführen:

    1. Erstellen sie eine neue Entwicklungsumgebung: azd env new
    2. Abrufen Ihrer Mandanten-ID: az account show --query tenantId -o tsv (Kopieren Sie die Ausgabe-ID für später)
    3. Abmelden: azd auth logout Befehl
    4. Melden Sie sich bei azd mit Ihrem tenantId-Wert aus Schritt 2 an: azd auth login --tenant-id <tenant_ID>

    Wenn Sie sich erfolgreich authentifizieren, wird in der Befehlsausgabe Logged in Azure als <your_user_alias> angezeigt.

  5. Melden Sie sich als Nächstes mit dem Azure CLI bei der Azure portal an:

    az login

    Sie werden aufgefordert, Ihre Anmeldeinformationen einzugeben, um sich bei Azure anzumelden.

    Ein Browserfenster bestätigt Ihre erfolgreiche Anmeldung. Schließen Sie das Fenster, und kehren Sie zu dieser Prozedur zurück.

  6. Führen Sie den folgenden Befehl aus, um die Lintinginfrastruktur für Ihr Azure-Abonnement bereitzustellen.

    Für diesen Befehl benötigen Sie die folgenden Informationen. Die meisten dieser Werte sind auf der Seite Overview für Ihre API Center-Ressource im Azure portal verfügbar.

    • Abonnementname und -ID
    • API-Zentrum Name
    • Ressourcengruppenname für das API Center
    • Bereitstellungsbereich für die Funktions-App (kann sich von Ihrer API Center-Region unterscheiden)
    azd up

  7. Folgen Sie den Anweisungen, um die erforderlichen Bereitstellungsinformationen und -einstellungen bereitzustellen. Weitere Informationen finden Sie unter Ausführen des Beispiels mit dem Azure Developer CLI (azd).

    Wenn die Bereitstellung fortschreitet, zeigt die Ausgabe die abgeschlossenen Bereitstellungsaufgaben an:

    Hinweis

    Es kann mehrere Minuten dauern, bis die Funktions-App bereitgestellt und für Azure bereitgestellt wird.

    Packaging services (azd package)

(✓) Done: Packaging service function
- Build Output: C:\GitHub\APICenter-Analyzer
- Package Output: C:\Users\<user>\AppData\Local\Temp\api-center-analyzer-function-azddeploy-0123456789.zip

Loading azd .env file from current environment

Provisioning Azure resources (azd provision)
Provisioning Azure resources can take some time.

Subscription: <your_selected_subscription>
Location: <your_selected_region_for_this_process>

You can view detailed progress in the Azure Portal:

https://portal.azure.com/#view/HubsExtension/DeploymentDetailsBlade/~/overview/id/%2Fsubscriptions%2F00001111-a2a2-b3b3-c4c4-dddddd555555%2Fproviders%2FMicrosoft.Resources%2Fdeployments%2F<your_azd_environment_name-0123456789>

(✓) Done: Resource group: <new_resource_group_for_function_app> (5.494s)
(✓) Done: App Service plan: <new_app_service_plan> (5.414s)
(✓) Done: Storage account: <new_storage_account> (25.918s)
(✓) Done: Log Analytics workspace: <new_workspace> (25.25s)
(✓) Done: Application Insights: <new_application_insights> (5.628s)
(✓) Done: Portal dashboard: <new_dashboard> (1.63s)
(✓) Done: Function App: <new_function_app> (39.402s)

    Die Ausgabe enthält einen Link zum Überwachen des Bereitstellungsfortschritts im Azure portal.

  8. Nach Abschluss der Bereitstellung stellt der Prozess die neue Funktions-App für die Azure portal bereit:

    Deploying services (azd deploy)

(✓) Done: Deploying service function
- Endpoint: https://<new_function_app>.azurewebsites.net/

Configuring EventGrid subscription for API Center

Examples from AI knowledge base

  9. Wenn die Bereitstellung abgeschlossen ist, bestätigen Sie, dass die neue Function-App vorhanden ist und die Funktion veröffentlicht wurde.

    Wenn die Funktion apicenter-analyer nicht aufgeführt ist oder der Status der Funktion nicht Enabled ist, veröffentlichen Sie die Funktion mit den Azure Functions Core Tools.

  10. Konfigurieren Sie ein Ereignisabonnement mit PowerShell oder einer Bash-Shell in Visual Studio Code.

Funktion bestätigen, die in Azure portal veröffentlicht wurde

Wenn die Bereitstellung abgeschlossen ist, vergewissern Sie sich, dass die neue Funktions-App im Azure portal vorhanden ist und die Funktion veröffentlicht wird.

  1. Melden Sie sich beim Abschnitt Azure portal an, navigieren Sie zum Abschnitt Function App, und wählen Sie ihre neue Funktions-App in der Liste aus.

  2. Bestätigen Sie auf der Seite Übersicht für die neue Funktions-App, dass der Status Status der Funktions-App Wird ausgeführt ist.

  3. Vergewissern Sie sich im Abschnitt "Funktionen ", dass die apicenter-analyer Funktion aufgelistet ist und der Statusaktiviert ist.

    Screenshot der Funktions-App im Azure portal mit dem Status

Veröffentlichen der Apicenter-Analyzer-Funktion mit Azure Functions Core Tools

Wenn der Bereitstellungsprozess die funktion apicenter-analyer nicht in der Funktions-App im Azure portal veröffentlicht, können Sie die folgenden Befehle in einem Visual Studio Codeterminal ausführen und den Vorgang abschließen.

  1. Führen Sie den folgenden Befehl aus, um zu bestätigen, dass die Funktion nicht in der Funktions-App veröffentlicht wird:

    Hinweis

    Dieser Befehl verwendet die neue Ressourcengruppe, die vom Bereitstellungsprozess für die Funktions-App und nicht die Ressourcengruppe für Ihr API Center erstellt wurde. Ersetzen Sie <function-app-name> und <new_resource_group_for_function_app> durch den Namen Ihrer Funktions-App und den Namen der Ressourcengruppe für die Funktions-App.

    az functionapp function list --name <function_app_name> --resource-group <new_resource_group_for_function_app> --query "[].name" -o tsv

    Die Befehlsausgabe sollte leer sein.

  2. Erweitern Sie im Explorer den src/functions Ordner, und öffnen Sie die ApiAnalyzerFunction.ts Datei. Diese Aktion bestätigt, dass die Umgebung so eingestellt ist, dass sie an der richtigen Position nach Inhalten sucht.

  3. Vergewissern Sie sich, dass Ihre Umgebung die npm-package manager- und Knotenlaufzeitumgebung enthält, und installieren Sie alle erforderlichen Tools:

    node --version
npm --version

  4. Installieren Sie nach Bedarf die Azure Functions Codetools in der Umgebung:

    npm install -g azure-functions-core-tools@4 --unsafe-perm true

  5. Führen Sie den folgenden Befehl aus, um den Funktionscode in der Funktions-App im Azure portal zu veröffentlichen. Ersetzen Sie <function-app-name> durch den Namen Ihrer Funktions-App.

    func azure functionapp publish <function_app_name> --typescript

    Der Befehl zeigt die folgende Ausgabe:

    Getting site publishing info...
[2026-02-26T19:58:38.779Z] Starting the function app deployment...
Uploading package...
Uploading 33.8 MB [###############################################################################]
Upload completed successfully.
Deployment completed successfully.
apicenter-analyzer - [eventGridTrigger]

  6. Bestätigen Sie im Azure-Portal, dass die Funktion apicenter-analyzer jetzt veröffentlicht und für Ihre Funktions-App aktiviert ist.

Konfigurieren des Ereignisabonnements

Nachdem die Funktion erfolgreich in der Funktions-App im Azure portal veröffentlicht wurde, können Sie ein Ereignisabonnement in Ihrem API Center erstellen, um die Funktions-App auszulösen, wenn eine API-Definitionsdatei hochgeladen oder aktualisiert wird.

  1. Rufen Sie die Ressourcen-ID Ihres API Centers ab. Ersetzen Sie <apic-name> durch Ihren API Center-Namen und <resource-group-name> durch den Namen der Ressourcengruppe für Ihr API Center.

    #! /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> durch den Namen Ihrer Funktions-App und <resource-group-name> durch den Namen der Ressourcengruppe Ihrer Funktions-App.

    #! /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-subscription create. 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 die Details des Ereignisabonnements an. Sie können auch Details über den Befehl az eventgrid event-subscription show abrufen:

    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.

  4. Navigieren Sie im Azure portal zum API Center, und bestätigen Sie das neue Ereignisabonnement unter Events>Event Subscriptions.

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

  1. Navigieren Sie zum API Center, und wählen Sie "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 Linting erfolgreich aufgerufen wurde.

    Screenshot der Metriken für das Ereignisabonnement im Portal.

    Hinweis

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

Nachdem das System die API-Definition analysiert hat, generiert das Lintingmodul basierend auf dem konfigurierten API-Stilleitfaden einen Bericht.

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 zum API Center, erweitern Sie " Bestand", und wählen Sie "Objekte" aus.

  2. Wählen Sie in der Ressourcenliste die API aus, für die Sie eine API-Definition hinzugefügt oder aktualisiert haben.

  3. Wählen Sie "Versionen" aus, und erweitern Sie dann die Zeile für die zu untersuchende API.

  4. Wählen Sie unter "Definition" den Definitionsnamen aus, den Sie hochgeladen oder aktualisiert haben.

  5. Wählen Sie die Registerkarte "Analyse " aus.

    Screenshot der Registerkarte

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

Sie können eine Zusammenfassung der Analyseberichte für alle API-Definitionen in Ihrem API Center anzeigen.

  • Navigieren Sie im Portal zu Ihrem API Center, erweitern Sie Governance, und wählen Sie API-Analyse aus.

    Screenshot der API-Analysezusammenfassung im Portal.

  • Das Symbol rechts in jeder Zeile öffnet den API-Analysebericht für die Definition.

Zugehöriger Inhalt

  • Last updated on