Delen via

API-analyse inschakelen in uw API-centrum - zelfbeheerd

In dit artikel wordt uitgelegd hoe u API-analyse inschakelt in Azure API Center om een linting-engine en triggers in te stellen. Deze mogelijkheden analyseren uw API-definities voor naleving van organisatiestijlregels, waarbij zowel afzonderlijke als overzichtsrapporten worden gegenereerd. API-analyse helpt bij het identificeren en corrigeren van veelvoorkomende fouten en inconsistenties in uw API-definities.

De volgende procedures ondersteunen geautomatiseerde implementatie van de linting-engine en het gebeurtenisabonnement in uw API-centrum. Gebruik de Azure Developer CLI (azd) voor implementatie van linting-infrastructuur in één stap voor een gestroomlijnd implementatieproces. De Azure CLI opdrachtvoorbeelden kunnen worden uitgevoerd in PowerShell of een bash-shell. Er worden, indien nodig, afzonderlijke opdrachtvoorbeelden gegeven.

Als u de engine en resources liever via manual deployment instelt, raadpleegt u de GitHub-opslagplaats van Azure API Center Analyzer voor instructies over het uitrollen van de functie-app en het configureren van het gebeurtenisabonnement.

Notitie

Azure API Center configureert automatisch een standaard linting-engine en afhankelijkheden voor API-analyse. Als u zelfbeheerde analyses inschakelt zoals beschreven in dit artikel, overschrijft u deze ingebouwde functies.

Overzicht van scenario

In dit scenario analyseert u API-definities in uw API-centrum met behulp van de Spectral open source linting-engine. Met een functie-app die is gebouwd met Azure Functions wordt de linting-engine uitgevoerd als reactie op gebeurtenissen in uw API-centrum. Spectral controleert of de API's die zijn gedefinieerd in een JSON- of YAML-specificatiedocument voldoen aan de regels in een aanpasbare API-stijlhandleiding. Er wordt een analyserapport gegenereerd dat u kunt bekijken in uw API-centrum.

In het volgende diagram ziet u de stappen voor het inschakelen van linting en analyse in uw API-centrum.

Diagram waarin wordt getoond hoe API linting werkt in Azure API Center.

  1. Implementeer een functie-app die de Spectral linting-engine uitvoert op een API-definitie.

  2. Configureer een gebeurtenisabonnement in een Azure API-centrum waarmee de functie-app wordt geactiveerd.

  3. Een gebeurtenis wordt geactiveerd door een API-definitie toe te voegen of te vervangen in het API-centrum.

  4. Bij ontvangst van de gebeurtenis roept de functie-app de Spectral linting-engine aan.

  5. De linting-engine controleert of de API's die in de definitie zijn gedefinieerd, voldoen aan de API-stijlhandleiding van de organisatie en genereert een rapport.

  6. Bekijk het analyserapport in het API-centrum.

Beperkingen

  • Linting ondersteunt momenteel alleen JSON- of YAML-specificatiebestanden, zoals OpenAPI- of AsyncAPI-specificatiedocumenten.

  • De linting-engine maakt standaard gebruik van de ingebouwde spectral:oas regelset. Zie op GitHub de Spectral-repository als u de regelset wilt uitbreiden of aangepaste API-stijlrichtlijnen wilt maken.

  • De functie-app die linting aanroept, wordt afzonderlijk in rekening gebracht en u beheert en onderhoudt deze.

Vereisten

Azd-implementatie gebruiken voor functie-app en gebeurtenisabonnement

De volgende procedures bevatten geautomatiseerde stappen voor de Azure Developer CLI (azd) om de functie-app en het gebeurtenisabonnement te configureren waarmee linting en analyse in uw API-centrum mogelijk zijn.

Notitie

Als u liever de engine en resources instelt met manual deployment, bekijkt u de GitHub-opslagplaats Azure API Center Analyzer voor hulp bij het implementeren van de functie-app en het configureren van het gebeurtenisabonnement.

Het voorbeeld uitvoeren met behulp van azd

  1. Kloon de voorbeeldopslagplaats Azure API Center Analyzer GitHub naar uw lokale computer.

  2. Start Visual Studio Code en selecteer File>Open Folder (Ctrl+K, Ctrl+O). Blader naar de map voor de APICenter-Analyzer gekloonde opslagplaats en kies Map selecteren.

  3. In de Visual Studio Code Activity Bar, selecteer Explorer (Ctrl+Shift+E), zodat u de mapstructuur van de opslagplaats kunt bekijken.

    • Vouw de resources/rulesets map uit en let op het oas.yaml bestand. Dit bestand weerspiegelt uw huidige API-stijlhandleiding. U kunt dit bestand wijzigen om te voldoen aan de behoeften van uw organisatie.

    • Vouw de src/functions map uit en let op het ApiAnalyzerFunction.ts bestand. Dit bestand bevat de functiecode voor de functie-app. U kunt dit bestand wijzigen om het gedrag van de functie aan te passen aan uw toepassingsvereisten.

  4. Open een terminal in Visual Studio Code en verifieer met de Azure Developer CLI (azd):

    azd auth login

    Aanbeveling

    U kunt verificatieproblemen in ontwikkelomgevingen voorkomen door de volgende opdrachten uit te voeren:

    1. Maak een nieuwe ontwikkelomgeving: azd env new
    2. Haal uw tenant-ID op: az account show --query tenantId -o tsv (kopieer de uitvoer-ID voor later)
    3. Afmelden: azd auth logout opdracht
    4. Meld u aan azd met uw tenantId waarde uit stap 2: azd auth login --tenant-id <tenant_ID>

    Wanneer u zich succesvol aanmeldt, wordt in de opdrachtuitvoer weergegeven Aangemeld bij Azure als <your_user_alias>.

  5. Meld u vervolgens aan bij de Azure portal met behulp van de Azure CLI:

    az login

    U wordt gevraagd uw referenties in te voeren om u aan te melden bij Azure.

    In een browservenster wordt bevestigd dat u bent aangemeld. Sluit het venster en ga terug naar deze procedure.

  6. Voer de volgende opdracht uit om de linting-infrastructuur te implementeren in uw Azure-abonnement.

    Voor deze opdracht hebt u de volgende informatie nodig. De meeste van deze waarden zijn beschikbaar op de pagina Overview voor uw API Center-resource in de Azure portal.

    • Abonnementsnaam en -id
    • Naam API-centrum
    • Resourcegroepnaam voor het API-centrum
    • Implementatieregio voor de functie-app (kan afwijken van uw API-centrumregio)
    azd up

  7. Volg de aanwijzingen om de vereiste implementatiegegevens en -instellingen op te geven. Zie Het uitvoeren van het voorbeeld met de Azure Developer CLI (azd) voor meer informatie.

    Wanneer de implementatie vordert, worden in de uitvoer de voltooide inrichtingstaken weergegeven:

    Notitie

    Het kan enkele minuten duren voordat de functie-app is ingericht en geïmplementeerd in Azure.

    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)

    De uitvoer bevat een koppeling om de voortgang van de implementatie in de Azure portal te controleren.

  8. Nadat het inrichten is voltooid, implementeert het proces de nieuwe functie-app in de Azure portal:

    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. Wanneer de implementatie is voltooid, bevestigt u dat de nieuwe functie-app aanwezig is en wordt de functie gepubliceerd.

    Als de apicenter-analyer-functie niet wordt vermeld of als de Status niet op Ingeschakeld staat, publiceer dan de functie met de Azure Functions Core Tools.

  10. Configureer een gebeurtenisabonnement met PowerShell of een bash-shell in Visual Studio Code.

Bevestig de functie die is gepubliceerd in Azure portal

Wanneer de implementatie is voltooid, controleert u of de nieuwe functie-app aanwezig is in de Azure portal en of de functie is gepubliceerd.

  1. Meld u aan bij de sectie Azure portal, blader naar de sectie Function App en selecteer uw nieuwe functie-app in de lijst.

  2. Controleer op de pagina Overzicht voor de nieuwe functie-app of de status van de functie-app draait.

  3. Controleer in de sectie Functies of de apicenter-analyer functie wordt weergegeven en of de status is ingeschakeld.

    Schermopname van de functie-app in de Azure portal met de functie Status Actief en Ingeschakeld.

De functie apicenter-analyzer publiceren met Azure Functions Core Tools

Als het implementatieproces de functie apicenter-analyer niet publiceert naar de functie-app in de Azure portal, kunt u de volgende opdrachten uitvoeren in een Visual Studio Code-terminal en het proces voltooien.

  1. Voer de volgende opdracht uit om te bevestigen dat de functie niet is gepubliceerd voor de functie-app.

    Notitie

    Met deze opdracht wordt de nieuwe resourcegroep gebruikt die is gemaakt door het implementatieproces voor de functie-app en niet de resourcegroep voor uw API-centrum. Vervang <function-app-name> met de naam van uw functie-app en <new_resource_group_for_function_app> met de naam van de resourcegroep voor de functie-app.

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

    De uitvoer van de opdracht moet leeg zijn.

  2. Vouw in Explorer de src/functions map uit en open het ApiAnalyzerFunction.ts bestand. Met deze actie wordt bevestigd dat de omgeving is ingesteld om te zoeken naar inhoud op de juiste locatie.

  3. Controleer of uw omgeving de npm-package manager en de runtime-omgeving voor knooppunten bevat en installeer indien nodig hulpprogramma's:

    node --version
npm --version

  4. Installeer indien nodig de Azure Functions Code Tools in de omgeving:

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

  5. Voer de volgende opdracht uit om de functiecode te publiceren naar de functie-app in de Azure portal. Vervang door <function-app-name> de naam van uw functie-app.

    func azure functionapp publish <function_app_name> --typescript

    De opdracht toont de volgende uitvoer:

    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. Controleer in de Azure portal of de functie apicenter-analyzer nu is publiceerd en ingeschakeld voor uw functie-app.

Gebeurtenisabonnement configureren

Nadat de functie is gepubliceerd naar de functie-app in de Azure portal, kunt u een gebeurtenisabonnement maken in uw API-centrum om de functie-app te activeren wanneer een API-definitiebestand wordt geüpload of bijgewerkt.

  1. Haal de resource-id van uw API-centrum op. Vervang <apic-name> en <resource-group-name> door de naam van uw API-centrum en de naam van de resourcegroep voor uw API-centrum.

    #! /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. Haal de resource-ID van de functie op in de functieapp. In dit voorbeeld is de functienaam apicenter-analyzer. Vervang <function-app-name> en <resource-group-name> door de naam van uw functie-app en de naam van de resourcegroep voor uw functie-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. Maak een gebeurtenisabonnement met behulp van de opdracht az eventgrid event-subscription create. Het gemaakte abonnement bevat gebeurtenissen voor het toevoegen of bijwerken van API-definities.

    #! /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

    In de opdrachtuitvoer worden details van het abonnement op gebeurtenissen weergegeven. U kunt ook details ophalen met behulp van de opdracht az eventgrid event-subscription show:

    az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"

    Notitie

    Het kan enige tijd duren voordat het gebeurtenisabonnement wordt doorgevoerd naar de functie-applicatie.

  4. Blader naar het API-centrum in de Azure portal en bevestig het nieuwe gebeurtenisabonnement onder Events>Event-abonnementen.

Trigger-gebeurtenis in uw API-centrum

Als u het gebeurtenisabonnement wilt testen, uploadt of bijwerkt u een API-definitiebestand dat is gekoppeld aan een API-versie in uw API-centrum. Upload bijvoorbeeld een OpenAPI- of AsyncAPI-document. Nadat het gebeurtenisabonnement is geactiveerd, roept de functie-app de API linting-engine aan om de API-definitie te analyseren.

Ga als volgt te werk om te bevestigen dat het gebeurtenisabonnement wordt geactiveerd:

  1. Blader naar uw API-centrum en selecteer Gebeurtenissen.

  2. Selecteer het tabblad Gebeurtenisabonnementen en selecteer het gebeurtenisabonnement voor uw functie-app.

  3. Controleer de metriek om te bevestigen dat het gebeurtenisabonnement wordt geactiveerd en linting succesvol is uitgevoerd.

    Schermopname van de metrische gegevens voor het gebeurtenisabonnement in de portal.

    Notitie

    Het kan enkele minuten duren voordat de metrische gegevens worden weergegeven.

Nadat het systeem de API-definitie heeft geanalyseerd, genereert de linting-engine een rapport op basis van de geconfigureerde API-stijlgids.

API-analyserapporten weergeven

U kunt het analyserapport voor uw API-definitie bekijken in de Azure portal. Nadat een API-definitie is geanalyseerd, bevat het rapport fouten, waarschuwingen en informatie op basis van de geconfigureerde API-stijlhandleiding.

In de portal kunt u ook een overzicht bekijken van analyserapporten voor alle API-definities in uw API-centrum.

Analyserapport voor een API-definitie

Het analyserapport voor een API-definitie weergeven in uw API-centrum:

  1. Blader in de portal naar uw API-centrum, vouw Inventaris uit en selecteer Assets.

  2. In de Asset lijst, selecteer de API waarvoor u een API-definitie hebt toegevoegd of bijgewerkt.

  3. Selecteer Versies en vouw vervolgens de rij voor de API uit die u wilt onderzoeken.

  4. Selecteer onder Definitie de naam van de definitie die u hebt geüpload of bijgewerkt.

  5. Selecteer het tabblad Analyse .

    Schermopname van het tabblad Analyse voor een API-definitie in de Azure portal.

Het API-analyserapport wordt geopend en geeft de API-definitie en fouten, waarschuwingen en informatie weer op basis van de geconfigureerde API-stijlhandleiding. In de volgende schermopname ziet u een voorbeeld van een API-analyserapport.

Schermopname van een API-analyserapport in de portal.

Overzicht van API-analyse

U kunt een overzicht van analyserapporten weergeven voor alle API-definities in uw API-centrum.

  • Blader in de portal naar uw API-centrum, vouw Governance uit en selecteer API-analyse.

    Schermopname van het overzicht van de API-analyse in de portal.

  • Het pictogram aan de rechterkant van elke rij opent het API-analyserapport voor de definitie.

Gerelateerde inhoud

  • Last updated on