Condividi tramite

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

Questo articolo illustra come abilitare l'analisi API in Centro API di Azure per configurare un motore di linting e i relativi trigger. Queste funzionalità analizzano le definizioni api per rispettare le regole di stile dell'organizzazione, generando report individuali e di riepilogo. L'analisi api consente di identificare e correggere gli errori e le incoerenze comuni nelle definizioni api.

Le procedure seguenti supportano la distribuzione automatica del motore di linting e dell'iscrizione agli eventi nell'hub delle API. Usare l'Azure Developer CLI (azd) per una distribuzione in un passaggio unico dell'infrastruttura di linting, garantendo un processo di distribuzione efficiente. Gli esempi di comandi Azure CLI possono essere eseguiti in PowerShell o in una shell bash. In base alle esigenze, vengono forniti esempi di comandi separati.

Se si preferisce configurare il motore e le risorse tramite manual deployment, vedere il repository Azure API Center Analyzer GitHub per indicazioni su come distribuire l'app per le funzioni e configurare la sottoscrizione di eventi.

Nota

Centro API di Azure configura automaticamente un motore di linting predefinito e le dipendenze per l'analisi delle API. Se si abilita l'analisi autogestita come descritto in questo articolo, si superano queste funzionalità predefinite.

Panoramica dello scenario

In questo scenario si analizzano le definizioni api nel centro API usando il motore di linting Spectral open source. Un'applicazione di funzioni costruita con Azure Functions esegue il motore di linting in risposta agli eventi nel hub 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.

Diagramma che illustra il funzionamento dell'api linting in Azure API Center.

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

  2. Configurare una sottoscrizione di eventi in un centro API Azure che attiva 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.

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 guides di stile API personalizzato, vedere il repository Spectral su GitHub.

  • L'app per le funzioni che richiama il linting è addebitata separatamente e viene gestita e mantenuta dall'utente.

Prerequisiti

Usare azd deployment per l'applicazione di funzioni e l'abbonamento di eventi

Le procedure seguenti forniscono passaggi automatizzati per l'interfaccia della riga di comando per sviluppatori Azure (azd) per configurare l'app per le funzioni e la sottoscrizione di eventi che abilitano il linting e l'analisi nel centro API.

Nota

Se si preferisce configurare il motore e le risorse con la distribuzione manual deployment, vedere il repository Azure API Center Analyzer GitHub per indicazioni su come distribuire l'app per le funzioni e configurare la sottoscrizione di eventi.

Eseguire l'esempio usando azd

  1. Clonare il repository di esempio Azure API Center Analyzer GitHub nel computer locale.

  2. Avviare Visual Studio Codice e selezionare File>Apri cartella (Ctrl+K, Ctrl+O). Accedere alla cartella APICenter-Analyzer del repository clonato e scegliere Seleziona cartella.

  3. Nella Visual Studio Code Activity Bar selezionare Explorer (Ctrl+Shift+E) per poter visualizzare la struttura della cartella del repository.

    • Espandere la resources/rulesets cartella e notare il oas.yaml file. Questo file riflette la guida di stile dell'API corrente. È possibile modificare questo file per soddisfare le esigenze dell'organizzazione.

    • Espandere la src/functions cartella e notare il ApiAnalyzerFunction.ts file. Questo file fornisce il codice della funzione per l'app per le funzioni. È possibile modificare questo file per modificare il comportamento della funzione in modo da soddisfare i requisiti dell'applicazione.

  4. Aprire un terminale in codice Visual Studio ed eseguire l'autenticazione con l'interfaccia della riga di comando di Azure Developer (azd):

    azd auth login

    Suggerimento

    È possibile evitare problemi di autenticazione in ambienti di sviluppo eseguendo i comandi seguenti:

    1. Creare un nuovo ambiente di sviluppo: azd env new
    2. Ottenere l'ID tenant: az account show --query tenantId -o tsv (copiare l'ID di output per l'uso successivo)
    3. Comando di disconnessione: azd auth logout
    4. Accedere a azd con il valore tenantId ottenuto dal passaggio 2: azd auth login --tenant-id <tenant_ID>

    Quando esegui l'autenticazione con successo, l'output del comando mostra Connesso a Azure come <il tuo alias utente>.

  5. Accedere quindi al Azure portal usando il Azure CLI:

    az login

    Viene richiesto di immettere le credenziali per accedere a Azure.

    Una finestra del browser conferma l'accesso riuscito. Chiudere la finestra e tornare a questa procedura.

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

    Per questo comando sono necessarie le informazioni seguenti. La maggior parte di questi valori è disponibile nella pagina Overview per la risorsa centro API nel Azure portal.

    • Nome e ID della sottoscrizione
    • Nome centro API
    • Nome del gruppo di risorse per il centro API
    • Area di distribuzione per l'app per le funzioni (può essere diversa dall'area del centro API)
    azd up

  7. Seguire le istruzioni per fornire le informazioni e le impostazioni di distribuzione necessarie. Per altre informazioni, vedere Esecuzione dell'esempio utilizzando la CLI di Azure Developer (azd).

    Man mano che la distribuzione procede, l'output mostra le attività di provisioning completate:

    Nota

    Il provisioning dell'applicazione per le funzioni e la sua distribuzione su Azure può richiedere alcuni minuti.

    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)

    L'output include un collegamento per monitorare lo stato di avanzamento della distribuzione nella Azure portal.

  8. Al termine del provisioning, il processo pubblica la nuova funzione app nel portale di Azure.

    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. Al termine della distribuzione, confirma la nuova app per le funzioni è presente e la funzione viene pubblicata.

    Se la funzione apicenter-analyer non è elencata o la funzione Status non è Enabled, pubblica la funzione usando gli strumenti di base di Azure Functions.

  10. Configurare una sottoscrizione di eventi usando PowerShell o una shell bash nel codice Visual Studio.

Confermare la funzione pubblicata in Azure portal

Al termine della distribuzione, verificare che la nuova app per le funzioni sia presente nella Azure portal e che la funzione venga pubblicata.

  1. Accedere alla sezione Azure portal, passare alla sezione Function App e selezionare la nuova app per le funzioni nell'elenco.

  2. Nella pagina Panoramica per la nuova app per le funzioni, verificare che Stato dell'app per le funzioni sia In esecuzione.

  3. Nella sezione Funzioni verificare che la apicenter-analyer funzione sia elencata e che lo stato sia Abilitato.

    Screenshot dell'app per le funzioni nel Azure portal che mostra lo stato in esecuzione e la funzione Enabled.

Pubblicare la funzione apicenter-analyzer con Azure Functions Core Tools

Se il processo di distribuzione non pubblica la funzione apicenter-analyer nell'app per le funzioni nel portale di Azure, è possibile eseguire i comandi seguenti in un terminale di Visual Studio Code e completare il processo.

  1. Eseguire il comando seguente per verificare che la funzione non sia pubblicata nell'app per le funzioni:

    Nota

    Questo comando usa il nuovo gruppo di risorse creato dal processo di distribuzione per l'app per le funzioni e non il gruppo di risorse per il centro API. Sostituire <function-app-name> e <new_resource_group_for_function_app> con il nome dell'app per le funzioni e il nome del gruppo di risorse per l'app per le funzioni.

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

    L'output del comando deve essere vuoto.

  2. In Esplora risorse espandere la src/functions cartella e aprire il ApiAnalyzerFunction.ts file. Questa azione conferma che l'ambiente è impostato per cercare il contenuto nella posizione corretta.

  3. Verificare che l'ambiente includa l'ambiente di runtime npm package manager e node e installare tutti gli strumenti in base alle esigenze:

    node --version
npm --version

  4. Se necessario, installare gli strumenti di codice Azure Functions nell'ambiente:

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

  5. Eseguire il comando seguente per pubblicare il codice della funzione nell'app per le funzioni nel Azure portal. Sostituire <function-app-name> con il nome della funzione dell'app.

    func azure functionapp publish <function_app_name> --typescript

    Il comando mostra l'output seguente:

    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. Nel portale di Azure, verificare che la funzione apicenter-analyzer sia ora pubblicata e abilitata per l'app per le funzioni.

Configurare la sottoscrizione di eventi

Dopo che la funzione è stata pubblicata correttamente nell'app per le funzioni nel Azure portal, è possibile creare una sottoscrizione di eventi nel centro API per attivare l'app per le funzioni quando viene caricato o aggiornato un file di definizione api.

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

    #! /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 il nome del gruppo di risorse per l'app per le funzioni.

    #! /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 evento usando il comando az eventgrid event-subscription create. La sottoscrizione creata include eventi per l'aggiunta o l'aggiornamento di definizioni 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 dell'iscrizione agli eventi. Puoi anche ottenere dettagli usando il comando az eventgrid event-subscription show:

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

    Nota

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

  4. Passare al centro API nel Azure portal e confermare la nuova sottoscrizione di eventi in Events>Event Subscriptions.

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 verificare che la sottoscrizione di eventi sia attivata:

  1. Passare al centro API e selezionare Eventi.

  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 attivata e che venga richiamata correttamente.

    Screenshot delle metriche per la sottoscrizione di eventi nel portale.

    Nota

    La visualizzazione delle metriche potrebbe richiedere alcuni minuti.

Dopo che il sistema analizza 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 nella Azure portal. 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 al centro API, espandere Inventario e selezionare Asset.

  2. Nell'elenco Asset selezionare l'API per cui è stata aggiunta o aggiornata una definizione API.

  3. Selezionare Versioni e quindi espandere la riga per l'API da esaminare.

  4. In Definizione selezionare il nome della definizione caricato o aggiornato.

  5. Selezionare la scheda Analisi .

    Screenshot della scheda Analisi per una definizione API nel Azure portal.

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.

Screenshot di un report di analisi API nel portale.

Riepilogo dell'analisi API

È possibile visualizzare un riepilogo dei report di analisi per tutte le definizioni api nel centro API.

  • Nel portale passare al centro API, espandere Governance e selezionare Analisi API.

    Screenshot del riepilogo dell'analisi api nel portale.

  • L'icona a destra di ogni riga apre il report di analisi API per la definizione.

Contenuto correlato

  • Last updated on