Abilitare l'analisi dell’API nel centro API - Gestita da Microsoft

  • Articolo

Questo articolo illustra come abilitare l'analisi dell’API nel Centro API di Azure senza doverla gestirla autonomamente (anteprima). 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.

Importante

L'analisi dell'API gestita nel Centro API configura automaticamente un motore di linting e le dipendenze necessarie. È anche possibile abilitare manualmente il linting e l'analisi usando una funzione di Azure personalizzata. Disabilitare qualsiasi funzione usata per il linting manuale prima di abilitare l'analisi dell'API gestita.

In questo scenario:

  1. Aggiungere un set di regole di linting (guida di stile delle API) nel centro API tramite l'estensione Visual Studio Code per Centro API di Azure.
  2. Il Centro API di Azure esegue automaticamente il linking quando si aggiunge o si aggiorna una definizione dell'API. Viene inoltre attivato per tutte le definizioni dell’API quando si distribuisce un set di regole al centro API.
  3. Esaminare i report di analisi dell’API nel portale di Azure per verificare la conformità delle definizioni dell’API alle regole della guida di stile.
  4. Facoltativamente, personalizzare il set di regole per le API dell'organizzazione. Testare il set di regole personalizzato in locale prima di distribuirlo nel centro API.

Limiti

  • Attualmente, vengono analizzati solo documenti di specifica OpenAPI in formato JSON o YAML.
  • Per impostazione predefinita, l'analisi viene abilitata tramite il set di regole spectral:oas. Per altre informazioni sulle regole predefinite, vedere il repository GitHub Spectral.
  • Attualmente, si configura un singolo set di regole, che viene applicato a tutte le definizioni OpenAPI del centro API.
  • Esistono limiti per il numero massimo di definizioni api analizzate. Il completamento dell'analisi può richiedere fino a 24 ore.

Prerequisiti

Abilitare l'analisi dell’API tramite Visual Studio Code

Per abilitare l'analisi dell’API tramite il set di regole di linting predefinito:

  1. In Visual Studio Code, aprire una cartella che verrà usata per gestire i set di regole del Centro API di Azure.

  2. Selezionare l'icona del Centro API di Azure nella barra delle attività.

  3. Nel riquadro Centro API, espandere la risorsa del centro API in cui abilitare l'analisi dell’API.

  4. Fare clic con il pulsante destro del mouse su Regole e selezionare Abilita analisi dell’API.

    Screenshot dell'abilitazione del linting e dell'analisi dell’API in Visual Studio Code.

Dopo che l'analisi dell'API è stata attivata correttamente, viene visualizzato un messaggio di notifica. Viene quindi creata una cartella per il centro API in .api-center-rules, nella radice della cartella di lavoro. La cartella per il centro API contiene:

  • Un file ruleset.yml che definisce le regole della guida di stile delle API predefinita usata dal motore di linting.
  • Una cartella functions con una funzione personalizzata di esempio, che è possibile usare per estendere il set di regole.

Con l'analisi abilitata, il motore di linting analizza le definizioni dell’API nel centro API in base al set di regole predefinito e genera report di analisi dell’API.

Visualizzare i report di analisi API

Visualizzare un riepilogo e i report di analisi per le definizioni dell’API nel portale di Azure. Dopo aver eseguito l'analisi delle definizioni dell’API, i report elencano errori, avvisi e informazioni in base alle regole della guida di stile dell’API configurata.

Per visualizzare un riepilogo dell'analisi 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.

    Screenshot del riepilogo dell'analisi API nel portale.

  3. Facoltativamente, selezionare l'icona Report di analisi dell’API per una definizione dell’API. Viene visualizzato il report di analisi della definizione dell’API, come illustrato nello screenshot seguente.

    Screenshot di un report di analisi API nel portale.

    Suggerimento

    È anche possibile visualizzare il report di analisi dell’API selezionando Analisi dalla barra del menu della definizione dell’API.

Personalizzare il set di regole

È possibile personalizzare il set di regole predefinito o sostituirlo a quello della guida di stile delle API per l'organizzazione. Ad esempio, è possibile estendere il set di regole o aggiungere funzioni personalizzate.

Per personalizzare o sostituire il set di regole:

  1. In Visual Studio Code, aprire la cartella .api-center-rules nella radice della cartella di lavoro.
  2. Nella cartella della risorsa del centro API, aprire il file ruleset.yml.
  3. Modificare o sostituire il contenuto in base alle esigenze.
  4. Salvare le modifiche apportate a ruleset.yml.

Testare il set di regole in locale

Prima di distribuire il set di regole personalizzato nel centro API, convalidarlo in locale. L'estensione del Centro API di Azure per Visual Studio Code offre un supporto integrato per eseguire il linting della specifica API con Spectral.

  1. In Visual Studio Code, usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi.

  2. Digitare Centro API di Azure: Impostare la Guida di stile API attiva e premere Invio.

  3. Scegliere Seleziona file locale e specificare il file ruleset.yml personalizzato. Premere INVIO.

    Attraverso questo passaggio, il set di regole personalizzato diventa la guida di stile dell'API attiva per il linting.

A questo punto, quando si apre un file di definizione dell'API basato su OpenAPI, viene automaticamente attivata un'operazione di linting locale in Visual Studio Code. I risultati vengono visualizzati inline nell'editor e nella finestra Problemi (Visualizza > Problemi o CTRL+MAIUSC+M).

Screenshot del linting di una definizione dell’API in Visual Studio Code.

Esaminare i risultati del linting. Apportare le modifiche necessarie al set di regole e continuare a testarlo in locale fino a quando non esegue la modalità desiderata.

Distribuire il set di regole al centro API

Per distribuire il set di regole personalizzato al centro API:

  1. In Visual Studio Code selezionare l'icona del Centro API di Azure dalla barra attività.
  2. Nel riquadro Centro API, espandere la risorsa del centro API in cui è stato personalizzato il set di regole.
  3. Fare clic con il pulsante destro del mouse su Regole e selezionare Distribuisci regole nel Centro API.

Dopo che le regole sono state distribuite correttamente nel centro API, viene visualizzato un messaggio di notifica. Il motore di linting usa il set di regole aggiornato per analizzare le definizioni dell’API.

Per vedere i risultati del linting con il set di regole aggiornato, visualizzare i report di analisi dell’API nel portale.

Contenuto correlato