Abilitare l'analisi dell’API nel centro API - autogestito

Questo articolo illustra come abilitare l'analisi dell'API nel Centro API di Azure configurando manualmente un motore di linting e i trigger. L'analisi dell’API offre funzionalità di linting per analizzare le definizioni dell’API nel centro API dell'organizzazione. Il linting garantisce che le definizioni dell’API siano conformi alle regole della guida di stile dell'organizzazione, generando report individuali e di riepilogo generali. Usare l'analisi dell’API per identificare e correggere errori e incoerenze comuni nelle definizioni dell’API.

Nota

In anteprima, il Centro API di Azure può anche configurare automaticamente un motore di linting e tutte le dipendenze e i trigger necessari. Altre informazioni.

Panoramica dello scenario

In questo scenario, si analizzano le definizioni dell'API nel centro API usando il motore di linting open source Spectral. Un'app di Funzioni di Azure esegue il motore di linting in risposta agli eventi del centro API. Spectral controlla che le API definite in un documento di specifica JSON o YAML risultino conformi alle regole di una guida di stile delle API personalizzabile. Viene generato un report di analisi che è possibile visualizzare nel centro API.

Il diagramma seguente illustra i passaggi per abilitare il linting e l'analisi nel centro API.

1. Distribuire un'app di Funzioni di Azure che esegue il motore di linting Spectral in una definizione dell'API.

2. Configurare una sottoscrizione di eventi in un centro API di Azure per attivare l'app per le funzioni.

3. Un evento viene attivato aggiungendo o sostituendo una definizione dell'API nel centro API.

4. Quando riceve l'evento, l'app per le funzioni richiama il motore di linting Spectral.

5. Il motore di linting verifica che le API specificate nella definizione relativa risultino conformi alla guida di stile delle API dell'organizzazione e generino un report.

6. Visualizzare il report di analisi nel centro API.

Opzioni per distribuire il motore di linting e la sottoscrizione di eventi

Questo articolo offre due opzioni per distribuire il motore di linting e la sottoscrizione di eventi nel centro API:

• Distribuzione automatizzata : usare Azure Developer CLI (azd) per la distribuzione in un unico passaggio dell'infrastruttura di linting. Questa opzione è consigliata per semplificare il processo di distribuzione.

• Distribuzione manuale: per distribuire l'app Funzioni di Azure e configurare la sottoscrizione di eventi, seguire le istruzioni dettagliate. Questa opzione è consigliata se si preferisce distribuire e gestire le risorse manualmente.

Limiti

• Il linting supporta attualmente solo file di specifica JSON o YAML, ad esempio documenti di specifica OpenAPI o AsyncAPI.
• Per impostazione predefinita, il motore di linting utilizza il spectral:oasset di regole predefinito. Per estendere il set di regole o creare guide di stile API personalizzate, vedere il repository GitHub Spectral.
• L'app per le funzioni di Azure che richiama il linting viene addebitata separatamente e viene gestita dall'utente.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il centro API.

• Il provider di risorse di Griglia di eventi registrato nella sottoscrizione. Se è necessario registrare il provider di risorse di Griglia di eventi, vedere Sottoscrivere eventi pubblicati da un partner con Griglia di eventi di Azure.

• Per l'interfaccia della riga di comando di Azure:

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

  Nota

  I comandi az apic richiedono l'estensione dell'interfaccia della riga di comando di Azure apic-extension. Se non sono stati usati comandi az apic, l'estensione può essere installata in modo dinamico quando si esegue il primo comando az apic oppure è possibile installarla manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.

  Vedere le note sulla versione per le modifiche e gli aggiornamenti più recenti in apic-extension.

  Nota

  Gli esempi di comandi dell'interfaccia della riga di comando di Azure riportati in questo articolo possono essere eseguiti in PowerShell o in una shell bash. Se necessario, a causa di una sintassi di variabile diversa, vengono forniti esempi di comandi separati per le due shell.

Distribuzione azd dell'app Funzioni di Azure e della sottoscrizione di eventi

Questa sezione illustra i passaggi automatizzati usando Azure Developer CLI per configurare l'app e la sottoscrizione di eventi di Funzioni di Azure che abilitano l'esecuzione di linting e analisi nel centro API. È anche possibile configurare manualmente le risorse.

Altri prerequisiti per questa opzione

• Azure Developer CLI (azd)

Eseguire l'esempio tramite azd

1. Clonare il repository GitHub e aprirlo in Visual Studio Code.

2. Passare alla cartella APICenter-Analyzer nel repository.

3. Nella cartella resources/rulesets è possibile trovare un file oas.yaml. Questo file riflette la guida di stile dell'API corrente e può essere modificata in base alle esigenze e ai requisiti dell'organizzazione.

4. Eseguire l'autenticazione con l'interfaccia della riga di comando per sviluppatori di Azure e l'interfaccia della riga di comando di Azure usando i comandi seguenti:

   azd auth login
   
   az login
   

5. Eseguire il comando seguente per distribuire l'infrastruttura di linting nella sottoscrizione di Azure.

   azd up
   

6. Seguire le istruzioni per specificare le informazioni e le impostazioni di distribuzione necessarie, ad esempio il nome dell'ambiente e il nome del centro API. Per informazioni dettagliate, vedere Esecuzione dell'esempio usando l'interfaccia della riga di comando per sviluppatori di Azure (azd).

   Nota

   La distribuzione può richiedere alcuni minuti.

7. Al termine della distribuzione, passare al centro API nel portale di Azure. Nel menu a sinistra selezionare Eventi>sottoscrizioni di eventi per visualizzare la sottoscrizione di eventi creata.

È ora possibile caricare un file di definizione API nel centro API per attivare la sottoscrizione di eventi ed eseguire il motore di linting.

Passaggi manuali per configurare l'app e la sottoscrizione di eventi di Funzioni di Azure

Questa sezione illustra la procedura di distribuzione manuale per configurare l'app e la sottoscrizione di eventi di Funzioni di Azure per abilitare l'esecuzione di linting e l'analisi nel centro API. È anche possibile usare Azure Developer CLI per la distribuzione automatizzata.

Altri prerequisiti per questa opzione

• Visual Studio Code con l'estensione Funzioni di Azure v1.10.4 o successiva.

Passaggio 1: Distribuire l'app Funzioni di Azure

Per distribuire l'app Funzioni di Azure che esegue la funzione di linting nelle definizioni dell'API:

1. Clonare il repository GitHub e aprirlo in Visual Studio Code.

2. Nella cartella resources/rulesets è possibile trovare un file oas.yaml. Questo file riflette la guida di stile dell'API corrente e può essere modificata in base alle esigenze e ai requisiti dell'organizzazione.

3. Facoltativamente, eseguire l'app per le funzioni in locale per testarla. Per informazioni dettagliate, vedere il file README nel repository.

4. Distribuire l'app per le funzioni in Azure. Per la procedura, vedere Avvio rapido: Creare una funzione in Azure con TypeScript usando Visual Studio Code.

   Nota

   La distribuzione dell'app per le funzioni potrebbe richiedere alcuni minuti.

5. Accedere al portale di Azure e passare all'app per le funzioni.

6. Nella pagina Panoramica, controllare i dettagli seguenti:

   • Verificare che lo Stato dell'app per le funzioni sia In esecuzione.
   • In Funzioni, controllare che lo Stato della funzione apicenter-analyzer sia Abilitato.

   

Passaggio 2. Configurare l'identità gestita nell'app per le funzioni

Per consentire all'app per le funzioni di accedere al centro API, configurare un'identità gestita per l'app per le funzioni. I passaggi seguenti illustrano come abilitare e configurare un'identità gestita assegnata dal sistema per l'app per le funzioni usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Portale

1. Nel portale di Azure, passare all'app per le funzioni e selezionare Identità nella sezione Impostazioni.
2. Nella scheda Assegnata dal sistema, impostare Stato su On e quindi selezionare Salva.

Ora che l'identità gestita è abilitata, assegnarvi il ruolo di Compliance Manager del Centro API di Azure per consentirle di accedere al centro API.

1. Nel portale di Azure, passare al centro API e selezionare Controllo di accesso (IAM).
2. Selezionare + Aggiungi > Aggiungi assegnazione di ruolo.
3. Selezionare Ruoli della funzione processo e quindi Compliance Manager del Centro API di Azure. Selezionare Avanti.
4. Nella pagina Membri, in Assegna accesso a, scegliere Identità gestita> e Seleziona membri.
5. Nella pagina Selezione identità gestite, cercare e scegliere l'identità gestita dell'app per le funzioni. Fare clic su Seleziona e quindi su Avanti.
6. Esaminare l'assegnazione di ruolo e selezionare Rivedi e assegna.

Interfaccia della riga di comando di Azure

1. Abilitare l'identità assegnata dal sistema dell'app per le funzioni usando il comando az functionapp identity assign. Sostituire <function-app-name> e <resource-group-name> con il nome dell'app per le funzioni e del gruppo di risorse. Il comando seguente archivia l'ID entità dell'identità gestita assegnata dal sistema nella variabile 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. Ottenere l'ID della risorsa del centro API. Sostituire <apic-name> e <resource-group-name> con il nome del centro API e del gruppo di risorse.

   #! /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. Assegnare all'identità gestita dell'app per le funzioni il ruolo Compliance Manager delle API di Azure nel Centro API usando il comando 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 
   

Passaggio 3. Configurare la sottoscrizione di eventi nel centro API

Creare ora una sottoscrizione di eventi nel centro API per attivare l'app per le funzioni quando viene caricato o aggiornato un file di definizione dell'API. La procedura seguente illustra come creare la sottoscrizione di eventi usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Portale

1. Nel portale di Azure, passare al centro API e selezionare Eventi.

2. Nella scheda Attività iniziali, selezionare Funzione di Azure.

3. Nella pagina Crea sottoscrizione di eventi, seguire questa procedura:

   1. Immettere un Nome descrittivo per la sottoscrizione di eventi e selezionare Schema griglia di eventi.

   2. In Dettagli argomento, immettere un Nome di argomento di sistema a piacere.

   3. In Tipi di evento, selezionare gli eventi seguenti:

      • Aggiunta della definizione dell'API
      • Aggiornamento della definizione dell'API

   4. In Dettagli endpoint, selezionare Funzione di Azure> Configurare un endpoint.

   5. Nella pagina Seleziona funzione di Azure, scegliere l'app per le funzioni e la funzione apicenter-linter configurata. Fare clic su Conferma selezione.

   6. Seleziona Crea.

      

4. Selezionare la scheda Sottoscrizioni di eventi e quindi Aggiorna. Verificare che lo Stato provisioning della sottoscrizione dell'evento sia Riuscito.

   

Interfaccia della riga di comando di Azure

1. Ottenere l'ID della risorsa del centro API. Sostituire <apic-name> e <resource-group-name> con il nome del centro API e del gruppo di risorse.

   #! /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. Ottenere l'ID della risorsa della funzione nell'app per le funzioni. In questo esempio, il nome della funzione è apicenter-analyzer. Sostituire <function-app-name> e <resource-group-name> con il nome dell'app per le funzioni e del gruppo di risorse.

   #! /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. Creare una sottoscrizione di eventi usando il comando az eventgrid event-subscription create. La sottoscrizione creata include eventi per l'aggiunta o l'aggiornamento delle definizioni dell'API.

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

   L'output del comando mostra i dettagli della sottoscrizione di eventi. È anche possibile ottenere i dettagli usando il comando az eventgrid event-subscription show. Ad esempio:

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

Nota

La propagazione della sottoscrizione di eventi all'app per le funzioni potrebbe richiedere del tempo.

Attivare l'evento nel centro API

Per testare la sottoscrizione di eventi, provare a caricare o aggiornare un file di definizione dell'API associato a una versione API nel centro API. Ad esempio, caricare un documento OpenAPI o AsyncAPI. Dopo l'attivazione della sottoscrizione di eventi, l'app per le funzioni richiama il motore di linting API per analizzare la definizione dell'API.

• Per i passaggi dettagliati per l'aggiunta di un'API, di una versione dell'API e di una definizione dell'API al centro API, vedere Esercitazione: Registrare le API nel centro API.
• Per creare un'API caricando un file di definizione dell'API usando l'interfaccia della riga di comando di Azure, vedere Registrare l'API da un file di specifica.

Per verificare che la sottoscrizione di eventi sia stata attivata:

1. Passare al centro API e selezionare Eventi nel menu a sinistra.

2. Selezionare la scheda Sottoscrizioni di eventi e scegliere la sottoscrizione di eventi per l'app per le funzioni.

3. Esaminare le metriche per verificare che la sottoscrizione dell'evento sia stata attivata e che il linting sia stato richiamato correttamente.

   

   Nota

   La visualizzazione delle metriche potrebbe richiedere alcuni minuti.

Dopo aver analizzato la definizione dell'API, il motore di linting genera un report basato sulla guida di stile dell'API configurata.

Visualizzare i report di analisi API

È possibile visualizzare il report di analisi per la definizione dell'API nel portale di Azure. Dopo l'analisi di una definizione dell'API, il report elenca gli errori, gli avvisi e le informazioni in base alla guida di stile dell'API configurata.

Nel portale è anche possibile visualizzare un riepilogo dei report di analisi per tutte le definizioni dell'API nel centro API.

Report di analisi per una definizione dell'API

Per visualizzare il report di analisi per una definizione dell'API nel centro API:

1. Nel portale, passare alla versione dell'API nel centro API in cui è stata aggiunta o aggiornata una definizione dell'API.
2. Nel menu a sinistra, in Dettagli, selezionare Definizioni.
3. Selezionare la definizione dell'API caricata o aggiornata.
4. Selezionare la scheda Analisi.

Si apre il report di analisi API che visualizza la definizione e gli errori dell'API, gli avvisi e le informazioni, in base alla guida di stile dell'API configurata. Lo screenshot seguente mostra un esempio di report di analisi API.

Riepilogo dell'analisi API

Per visualizzare un riepilogo dei report di analisi per tutte le definizioni dell'API nel centro API:

1. Nel portale, passare al proprio centro API.

2. Nel menu a sinistra, in Governance, selezionare Analisi API. Viene visualizzato il riepilogo.

   

Contenuto correlato

Altre informazioni su Griglia di eventi:

• Abilitare l'analisi dell’API nel centro API - Gestita da Microsoft
• Argomenti di sistema in Griglia di eventi di Azure
• Distribuzione push di Griglia di eventi - Concetti
• Schema di Griglia di eventi per centro API di Azure