Linting en analyse inschakelen voor API-governance in uw API-centrum

In dit artikel wordt beschreven hoe u linting kunt inschakelen voor het analyseren van API-definities in het API-centrum van uw organisatie voor overeenstemming met de API-stijlregels van uw organisatie. Linting genereert een analyserapport dat u kunt openen in uw API-centrum. Gebruik API-linting en -analyse om veelvoorkomende fouten en inconsistenties in uw API-definities te detecteren.

Overzicht van scenario

In dit scenario analyseert u API-definities in uw API-centrum met behulp van de open source linting-engine van Spectral . Een Azure Functions-app voert de linting-engine uit 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 rapport gegenereerd over API-naleving 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.

1. Implementeer een Azure Functions-app waarop de Spectral linting-engine wordt uitgevoerd op een API-definitie.

2. Configureer een gebeurtenisabonnement in een Azure API-centrum om de functie-app te activeren.

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.

Opties voor het implementeren van de linting-engine en het gebeurtenisabonnement

Dit artikel bevat twee opties voor het implementeren van de linting-engine en het gebeurtenisabonnement in uw API-centrum:

• Geautomatiseerde implementatie : gebruik de Azure Developer CLI (azd) voor implementatie in één stap van de linting-infrastructuur. Deze optie wordt aanbevolen voor een gestroomlijnd implementatieproces.

• Handmatige implementatie : volg stapsgewijze instructies om de Azure Functions-app te implementeren en het gebeurtenisabonnement te configureren. Deze optie wordt aanbevolen als u de resources liever handmatig wilt implementeren en beheren.

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. Als u de regelset wilt uitbreiden of aangepaste API-stijlhulplijnen wilt maken, raadpleegt u de GitHub-opslagplaats Spectral.
• De Azure-functie-app die linting aanroept, wordt afzonderlijk in rekening gebracht en u beheert en onderhoudt deze.

Vereisten

• Een API-centrum in uw Azure-abonnement. Als u er nog geen hebt gemaakt, raadpleegt u quickstart: Uw API-centrum maken.

• De Event Grid-resourceprovider die is geregistreerd in uw abonnement. Als u de Event Grid-resourceprovider moet registreren, raadpleegt u Abonneren op gebeurtenissen die zijn gepubliceerd door een partner met Azure Event Grid.

• Voor Azure CLI:

  • Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

    

  • Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

    • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

    • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

    • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

  Notitie

  az apic voor opdrachten is de apic-extension Azure CLI-extensie vereist. Als u geen opdrachten hebt gebruikt az apic , kan de extensie dynamisch worden geïnstalleerd wanneer u uw eerste az apic opdracht uitvoert of kunt u de extensie handmatig installeren. Meer informatie over Azure CLI-extensies.

  Zie de releaseopmerkingen voor de meest recente wijzigingen en updates in de apic-extension.

  Notitie

  Voorbeelden van Azure CLI-opdrachten in dit artikel kunnen worden uitgevoerd in PowerShell of een bash-shell. Indien nodig vanwege verschillende syntaxis van variabelen, worden er afzonderlijke opdrachtvoorbeelden gegeven voor de twee shells.

azd implementatie van Azure Functions-app en gebeurtenisabonnement

Deze sectie bevat geautomatiseerde stappen met behulp van de Azure Developer CLI om de Azure Functions-app en het gebeurtenisabonnement te configureren waarmee linting en analyse in uw API-centrum mogelijk is. U kunt de resources ook handmatig configureren.

Andere vereisten voor deze optie

• Azure Developer CLI (azd)

Het voorbeeld uitvoeren met azd

1. Kloon de GitHub-opslagplaats en open deze in Visual Studio Code.

2. Wijzig de map in de APICenter-Analyzer map in de opslagplaats.

3. In de resources/rulesets map vindt u een oas.yaml bestand. Dit bestand weerspiegelt uw huidige API-stijlhandleiding en kan worden gewijzigd op basis van de behoeften en vereisten van uw organisatie.

4. Verifieer met de Azure Developer CLI en de Azure CLI met behulp van de volgende opdrachten:

   azd auth login
   
   az login
   

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

   azd up
   

6. Volg de aanwijzingen om de vereiste implementatiegegevens en -instellingen op te geven, zoals de omgevingsnaam en de naam van het API-centrum. Zie Het voorbeeld uitvoeren met behulp van de Azure Developer CLI (azd) voor meer informatie.

   Notitie

   De implementatie kan enkele minuten duren.

7. Nadat de implementatie is voltooid, gaat u naar uw API-centrum in Azure Portal. Selecteer in het linkermenu gebeurtenissengebeurtenissenabonnementen> om het gebeurtenisabonnement weer te geven dat is gemaakt.

U kunt nu een API-definitiebestand uploaden naar uw API-centrum om het gebeurtenisabonnement te activeren en de linting-engine uit te voeren.

Handmatige stappen voor het configureren van een Azure Functions-app en gebeurtenisabonnement

Deze sectie bevat de handmatige implementatiestappen voor het configureren van de Azure Functions-app en het gebeurtenisabonnement om linting en analyse in uw API-centrum in te schakelen. U kunt ook de Azure Developer CLI gebruiken voor geautomatiseerde implementatie.

Andere vereisten voor deze optie

• Visual Studio Code met de Azure Functions-extensie v1.10.4 of hoger.

Stap 1. Uw Azure Functions-app implementeren

De Azure Functions-app implementeren die de linting-functie uitvoert op API-definities:

1. Kloon de GitHub-opslagplaats en open deze in Visual Studio Code.

2. In de resources/rulesets map vindt u een oas.yaml bestand. Dit bestand weerspiegelt uw huidige API-stijlhandleiding en kan worden gewijzigd op basis van de behoeften en vereisten van uw organisatie.

3. Voer desgewenst de functie-app lokaal uit om deze te testen. Zie het README-bestand in de opslagplaats voor meer informatie.

4. Implementeer de functie-app in Azure. Zie Quickstart: Een functie maken in Azure met TypeScript met Behulp van Visual Studio Code voor stappen.

   Notitie

   Het implementeren van de functie-app kan enkele minuten duren.

5. Meld u aan bij Azure Portal en ga naar de functie-app.

6. Controleer op de overzichtspagina de volgende details:

   • Controleer of de status van de functie-app wordt uitgevoerd.
   • Controleer onder Functions of de status van de functie apicenter-analyzer is ingeschakeld.

   

Stap 2. Beheerde identiteit configureren in uw functie-app

Als u de functie-app toegang wilt geven tot het API-centrum, configureert u een beheerde identiteit voor de functie-app. In de volgende stappen ziet u hoe u een door het systeem toegewezen beheerde identiteit voor de functie-app inschakelt en configureert met behulp van Azure Portal of de Azure CLI.

Portal

1. Navigeer in Azure Portal naar uw functie-app en selecteer Identiteit in de sectie Instellingen.
2. Stel op het tabblad Systeem toegewezen de status in op Aan en selecteer Opslaan.

Nu de beheerde identiteit is ingeschakeld, wijst u deze de rol Azure API Center Compliance Manager toe voor toegang tot het API-centrum.

1. Navigeer in Azure Portal naar uw API-centrum en selecteer Toegangsbeheer (IAM).
2. Selecteer + Roltoewijzing toevoegen>.
3. Selecteer Functierollen voor taken en selecteer vervolgens Compliancebeheer voor Azure API Center. Selecteer Volgende.
4. Selecteer op de pagina Leden in Toegang toewijzen de optie Beheerde identiteit > en leden selecteren.
5. Zoek en selecteer op de pagina Beheerde identiteiten selecteren de beheerde identiteit van de functie-app. Klik op Selecteren en vervolgens op Volgende.
6. Controleer de roltoewijzing en selecteer Beoordelen en toewijzen.

Azure-CLI

1. Schakel de door het systeem toegewezen identiteit van de functie-app in met behulp van de opdracht az functionapp identity assign . Vervang en vervang <function-app-name> deze <resource-group-name> door de naam van uw functie-app en de naam van de resourcegroep. Met de volgende opdracht wordt de principal-id van de door het systeem toegewezen beheerde identiteit opgeslagen in de principalID variabele.

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

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

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

3. Wijs de beheerde identiteit van de functie-app toe aan de rol Azure API Center Compliance Manager in het API-centrum met behulp van de opdracht az role assignment create .

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

Stap 3. Gebeurtenisabonnement configureren in uw API-centrum

Maak nu een gebeurtenisabonnement in uw API-centrum om de functie-app te activeren wanneer een API-definitiebestand wordt geüpload of bijgewerkt. In de volgende stappen ziet u hoe u het gebeurtenisabonnement maakt met behulp van Azure Portal of de Azure CLI.

Portal

1. Navigeer in Azure Portal naar uw API-centrum en selecteer Gebeurtenissen.

2. Selecteer Azure Function op het tabblad Aan de slag.

3. Ga als volgt te werk op de pagina Gebeurtenisabonnement maken :

   1. Voer een beschrijvende naam in voor het gebeurtenisabonnement en selecteer Event Grid-schema.

   2. Voer in Onderwerpdetails een systeemonderwerpnaam van uw keuze in.

   3. Selecteer in Gebeurtenistypen de volgende gebeurtenissen:

      • API-definitie toegevoegd
      • API-definitie bijgewerkt

   4. Selecteer in Eindpuntdetails de optie Azure-functie > Een eindpunt configureren.

   5. Selecteer op de pagina Azure-functie selecteren de functie-app en de apicenter-linter-functie die u hebt geconfigureerd. Klik op Selectie bevestigen.

   6. Selecteer Maken.

      

4. Selecteer het tabblad Gebeurtenisabonnementen en selecteer Vernieuwen. Controleer of de inrichtingsstatus van het gebeurtenisabonnement is geslaagd.

   

Azure-CLI

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

   #! /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 functie-app. In dit voorbeeld is de functienaam apicenter-analyzer. Vervang <function-app-name> en vervang deze <resource-group-name> door de naam van uw functie-app en de naam van de resourcegroep.

   #! /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 abonnement dat is gemaakt, 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 uitvoer van de opdracht ziet u details van het gebeurtenisabonnement. U kunt ook details ophalen met behulp van de opdracht az eventgrid event-subscription show . Bijvoorbeeld:

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

Notitie

Het kan even duren voordat het gebeurtenisabonnement is doorgegeven aan de functie-app.

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.

• Zie Zelfstudie: API's registreren in uw API-centrum voor gedetailleerde stappen voor het toevoegen van een API-versie, API-versie en API-definitie aan uw API-centrum.
• Als u een API wilt maken door een API-definitiebestand te uploaden met behulp van de Azure CLI, raadpleegt u API registreren vanuit een specificatiebestand.

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

1. Navigeer naar uw API-centrum en selecteer Gebeurtenissen in het linkermenu.

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

3. Controleer de metrische gegevens om te bevestigen dat het gebeurtenisabonnement is geactiveerd en dat linting is aangeroepen.

   

   Notitie

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

Nadat de API-definitie is geanalyseerd, genereert de linting-engine een rapport op basis van de geconfigureerde API-stijlhandleiding.

API-analyserapporten weergeven

U kunt het analyserapport voor uw API-definitie bekijken in 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. Navigeer in de portal naar de API-versie in uw API-centrum waar u een API-definitie hebt toegevoegd of bijgewerkt.
2. Selecteer Definities in het linkermenu onder Details.
3. Selecteer de API-definitie die u hebt geüpload of bijgewerkt.
4. Selecteer het tabblad Analyse .

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.

Overzicht van API-analyse

Een overzicht van analyserapporten weergeven voor alle API-definities in uw API-centrum:

1. Navigeer in de portal naar uw API-centrum.

2. Selecteer API-analyse in het linkermenu onder Governance. De samenvatting wordt weergegeven.

   

Gerelateerde inhoud

Meer informatie over Event Grid:

• Systeemonderwerpen in Azure Event Grid
• Event Grid-pushlevering - concepten
• Event Grid-schema voor Azure API Center