Aktivera API-analys i DITT API Center – självhanterad

Den här artikeln beskriver hur du aktiverar API-analys i Azure API Center genom att manuellt konfigurera en lintningsmotor och utlösare. API-analys erbjuder lintningsfunktioner för att analysera API-definitioner i din organisations API Center. Linting säkerställer att dina API-definitioner följer organisationens stilregler och genererar både enskilda rapporter och sammanfattningsrapporter. Använd API-analys för att identifiera och korrigera vanliga fel och inkonsekvenser i DINA API-definitioner.

Kommentar

I förhandsversionen kan Azure API Center också automatiskt konfigurera en lintningsmotor och eventuella nödvändiga beroenden och utlösare. Läs mer.

Scenarioöversikt

I det här scenariot analyserar du API-definitioner i api-centret med hjälp av lintningsmotorn Spectral öppen källkod. En Azure Functions-app kör lintningsmotorn som svar på händelser i api-centret. Spectral kontrollerar att API:erna som definierats i ett JSON- eller YAML-specifikationsdokument överensstämmer med reglerna i en anpassningsbar API-formatguide. En analysrapport genereras som du kan visa i api-centret.

Följande diagram visar stegen för att aktivera lintning och analys i api-centret.

1. Distribuera en Azure Functions-app som kör lintningsmotorn Spectral i en API-definition.

2. Konfigurera en händelseprenumeration i ett Azure API Center för att utlösa funktionsappen.

3. En händelse utlöses genom att lägga till eller ersätta en API-definition i API Center.

4. När du tar emot händelsen anropar funktionsappen lintingmotorn Spectral.

5. Lintningsmotorn kontrollerar att API:erna som definierats i definitionen överensstämmer med organisationens API-formatguide och genererar en rapport.

6. Visa analysrapporten i API-centret.

Alternativ för att distribuera lintingmotorn och händelseprenumerationen

Den här artikeln innehåller två alternativ för att distribuera lintningsmotorn och händelseprenumerationen i DITT API Center:

• Automatiserad distribution – Använd Azure Developer CLI (azd) för enstegsdistribution av linting-infrastruktur. Det här alternativet rekommenderas för en effektiv distributionsprocess.

• Manuell distribution – Följ stegvisa anvisningar för att distribuera Azure Functions-appen och konfigurera händelseprenumerationen. Det här alternativet rekommenderas om du föredrar att distribuera och hantera resurserna manuellt.

Begränsningar

• Linting stöder för närvarande endast JSON- eller YAML-specifikationsfiler, till exempel OpenAPI- eller AsyncAPI-specifikationsdokument.
• Som standard använder lintningsmotorn den inbyggda spectral:oas regeluppsättningen. Information om hur du utökar regeluppsättningen eller skapar anpassade API-formatguider finns i Spectral GitHub-lagringsplatsen.
• Azure-funktionsappen som anropar linting debiteras separat och du hanterar och underhåller den.

Förutsättningar

• Ett API-center i din Azure-prenumeration. Om du inte redan har skapat ett kan du läsa Snabbstart: Skapa ditt API-center.

• Event Grid-resursprovidern som är registrerad i din prenumeration. Om du behöver registrera Event Grid-resursprovidern kan du läsa Prenumerera på händelser som publicerats av en partner med Azure Event Grid.

• För Azure CLI:

  • Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

    

  • Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

    • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

    • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

    • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

  Kommentar

  az apic kommandon kräver Azure CLI-tillägget apic-extension . Om du inte har använt az apic kommandon kan tillägget installeras dynamiskt när du kör ditt första az apic kommando, eller så kan du installera tillägget manuellt. Läs mer om Azure CLI-tillägg.

  Se viktig information för de senaste ändringarna och uppdateringarna apic-extensioni .

  Kommentar

  Azure CLI-kommandoexempel i den här artikeln kan köras i PowerShell eller ett bash-gränssnitt. Vid behov på grund av olika variabelsyntax tillhandahålls separata kommandoexempel för de två gränssnitten.

azd distribution av Azure Functions-appen och händelseprenumeration

Det här avsnittet innehåller automatiserade steg med hjälp av Azure Developer CLI för att konfigurera Azure Functions-appen och händelseprenumerationen som möjliggör lintning och analys i DITT API Center. Du kan också konfigurera resurserna manuellt.

Andra förutsättningar för det här alternativet

• Azure Developer CLI (azd)

Kör exemplet med azd

1. Klona GitHub-lagringsplatsen och öppna den i Visual Studio Code.

2. Ändra katalogen till APICenter-Analyzer mappen på lagringsplatsen.

3. resources/rulesets I mappen hittar du en oas.yaml fil. Den här filen visar den aktuella API-formatguiden och kan ändras baserat på organisationens behov och krav.

4. Autentisera med Azure Developer CLI och Azure CLI med följande kommandon:

   azd auth login
   
   az login
   

5. Kör följande kommando för att distribuera linting-infrastrukturen till din Azure-prenumeration.

   azd up
   

6. Följ anvisningarna för att ange nödvändig distributionsinformation och inställningar, till exempel miljönamnet och API Center-namnet. Mer information finns i Köra exemplet med hjälp av Azure Developer CLI (azd).

   Kommentar

   Distributionen kan ta några minuter.

7. När distributionen är klar går du till API-centret i Azure Portal. I den vänstra menyn väljer du Händelser>Händelseprenumerationer för att visa händelseprenumerationen som skapades.

Nu kan du ladda upp en API-definitionsfil till api-centret för att utlösa händelseprenumerationen och köra lintingmotorn.

Manuella steg för att konfigurera Azure Functions-app och händelseprenumeration

Det här avsnittet innehåller de manuella distributionsstegen för att konfigurera Azure Functions-appen och händelseprenumerationen för att aktivera lintning och analys i DITT API Center. Du kan också använda Azure Developer CLI för automatisk distribution.

Andra förutsättningar för det här alternativet

• Visual Studio Code med Azure Functions-tillägget v1.10.4 eller senare.

Steg 1. Distribuera din Azure Functions-app

Så här distribuerar du Azure Functions-appen som kör lintningsfunktionen i API-definitioner:

1. Klona GitHub-lagringsplatsen och öppna den i Visual Studio Code.

2. resources/rulesets I mappen hittar du en oas.yaml fil. Den här filen visar den aktuella API-formatguiden och kan ändras baserat på organisationens behov och krav.

3. Du kan också köra funktionsappen lokalt för att testa den. Mer information finns i README-filen på lagringsplatsen.

4. Distribuera funktionsappen till Azure. Anvisningar finns i Snabbstart: Skapa en funktion i Azure med TypeScript med Hjälp av Visual Studio Code.

   Kommentar

   Det kan ta några minuter att distribuera funktionsappen.

5. Logga in på Azure Portal och gå till funktionsappen.

6. På sidan Översikt kontrollerar du följande information:

   • Kontrollera att funktionsappens status är Körs.
   • Under Funktioner bekräftar du att status för funktionen apicenter-analyzer är Aktiverad.

   

Steg 2. Konfigurera hanterad identitet i funktionsappen

Om du vill göra det möjligt för funktionsappen att komma åt API-centret konfigurerar du en hanterad identitet för funktionsappen. Följande steg visar hur du aktiverar och konfigurerar en systemtilldelad hanterad identitet för funktionsappen med hjälp av Azure Portal eller Azure CLI.

Portal

1. I Azure Portal navigerar du till funktionsappen och väljer Identitet under avsnittet Inställningar.
2. På fliken Systemtilldelat anger du Status till På och väljer sedan Spara.

Nu när den hanterade identiteten är aktiverad tilldelar du rollen Azure API Center Compliance Manager för åtkomst till API Center.

1. I Azure Portal går du till API-centret och väljer Åtkomstkontroll (IAM)..
2. Välj + Lägg till lägg till > rolltilldelning.
3. Välj Jobbfunktionsroller och välj sedan Azure API Center Compliance Manager. Välj Nästa.
4. På sidan Medlemmar går du till Tilldela åtkomst till och väljer Hanterad identitet > + Välj medlemmar.
5. På sidan Välj hanterade identiteter söker du efter och väljer funktionsappens hanterade identitet. Klicka på Välj och sedan på Nästa.
6. Granska rolltilldelningen och välj Granska + tilldela.

Azure CLI

1. Aktivera funktionsappens systemtilldelade identitet med kommandot az functionapp identity assign . Ersätt <function-app-name> och <resource-group-name> med funktionsappens namn och resursgruppsnamn. Följande kommando lagrar huvud-ID:t för den systemtilldelade hanterade identiteten i variabeln principalID .

   #! /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. Hämta resurs-ID:t för ditt API-center. Ersätt <apic-name> och <resource-group-name> med namnet på API-centret och resursgruppens namn.

   #! /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. Tilldela funktionsappens hanterade identitet rollen Azure API Center Compliance Manager i API Center med kommandot 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 
   

Steg 3. Konfigurera händelseprenumeration i DITT API Center

Skapa nu en händelseprenumeration i API Center för att utlösa funktionsappen när en API-definitionsfil laddas upp eller uppdateras. Följande steg visar hur du skapar händelseprenumerationen med hjälp av Azure Portal eller Azure CLI.

Portal

1. I Azure Portal går du till API-centret och väljer Händelser.

2. På fliken Kom igång väljer du Azure-funktion.

3. Gör följande på sidan Skapa händelseprenumeration :

   1. Ange ett beskrivande namn för händelseprenumerationen och välj Event Grid-schema.

   2. I Ämnesinformation anger du valfritt systemämnesnamn .

   3. I Händelsetyper väljer du följande händelser:

      • API-definition har lagts till
      • API-definitionen har uppdaterats

   4. I Slutpunktsinformation väljer du Azure-funktion > Konfigurera en slutpunkt.

   5. På sidan Välj Azure-funktion väljer du funktionsappen och den apicenter-linter-funktion som du har konfigurerat. Klicka på Bekräfta markering.

   6. Välj Skapa.

      

4. Välj fliken Händelseprenumerationer och välj Uppdatera. Bekräfta att etableringstillståndet för händelseprenumerationen är Lyckades.

   

Azure CLI

1. Hämta resurs-ID:t för ditt API-center. Ersätt <apic-name> och <resource-group-name> med namnet på API-centret och resursgruppens namn.

   #! /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. Hämta resurs-ID för funktionen i funktionsappen. I det här exemplet är funktionsnamnet apicenter-analyzer. Ersätt <function-app-name> och <resource-group-name> med funktionsappens namn och resursgruppsnamn.

   #! /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. Skapa en händelseprenumeration med kommandot az eventgrid event-subscription create . Prenumerationen som skapas innehåller händelser för att lägga till eller uppdatera API-definitioner.

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

   Kommandoutdata visar information om händelseprenumerationen. Du kan också få information med kommandot az eventgrid event-subscription show . Till exempel:

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

Kommentar

Det kan ta en kort tid innan händelseprenumerationen sprids till funktionsappen.

Utlösarhändelse i DITT API Center

Testa händelseprenumerationen genom att prova att ladda upp eller uppdatera en API-definitionsfil som är associerad med en API-version i API Center. Du kan till exempel ladda upp ett OpenAPI- eller AsyncAPI-dokument. När händelseprenumerationen har utlösts anropar funktionsappen API-lintningsmotorn för att analysera API-definitionen.

• Detaljerade steg för att lägga till en API-, API-version och API-definition i API-centret finns i Självstudie: Registrera API:er i ditt API Center.
• Information om hur du skapar ett API genom att ladda upp en API-definitionsfil med hjälp av Azure CLI finns i Registrera API från en specifikationsfil.

Bekräfta att händelseprenumerationen utlöstes:

1. Gå till API-centret och välj Händelser på den vänstra menyn.

2. Välj fliken Händelseprenumerationer och välj händelseprenumerationen för funktionsappen.

3. Granska måtten för att bekräfta att händelseprenumerationen utlöstes och att linting anropades korrekt.

   

   Kommentar

   Det kan ta några minuter innan måtten visas.

När du har analyserat API-definitionen genererar lintningsmotorn en rapport baserat på den konfigurerade API-formatguiden.

Visa API-analysrapporter

Du kan visa analysrapporten för din API-definition i Azure Portal. När en API-definition har analyserats visar rapporten fel, varningar och information baserat på den konfigurerade API-formatguiden.

I portalen kan du också visa en sammanfattning av analysrapporter för alla API-definitioner i ditt API Center.

Analysrapport för en API-definition

Så här visar du analysrapporten för en API-definition i api-centret:

1. I portalen navigerar du till API-versionen i api-centret där du har lagt till eller uppdaterat en API-definition.
2. I den vänstra menyn går du till Information och väljer Definitioner.
3. Välj den API-definition som du laddade upp eller uppdaterade.
4. Välj fliken Analys .

API-analysrapporten öppnas och visar API-definition och fel, varningar och information baserat på den konfigurerade API-formatguiden. Följande skärmbild visar ett exempel på en API-analysrapport.

Sammanfattning av API-analys

Så här visar du en sammanfattning av analysrapporter för alla API-definitioner i api-centret:

1. Gå till API-centret i portalen.

2. I den vänstra menyn, under Styrning, väljer du API-analys. Sammanfattningen visas.

   

Relaterat innehåll

Läs mer om Event Grid:

• Aktivera API-analys i ditt API Center – Microsoft managed
• Systemämnen i Azure Event Grid
• Event Grid-pushleverans – begrepp
• Event Grid-schema för Azure API Center