Analizzare le API nel centro API - Gestito da Microsoft

Il centro API dell'organizzazione include le funzionalità di linting gestite da Microsoft integrate (anteprima) per analizzare le definizioni API e garantirne la conformità alle regole di stile dell'organizzazione, generando report individuali e riepilogativi. L'analisi api identifica e consente di correggere gli errori comuni e le incoerenze nelle definizioni api.

Con l'analisi delle API:

• Centro API di Azure analizza automaticamente le definizioni api ogni volta che si aggiunge o si aggiorna una definizione API. Il linting per le definizioni API viene eseguito per impostazione predefinita con un spectral:oas set di regole (guida di stile API).
• I report di analisi API vengono generati nella portale di Azure, che illustrano come le definizioni API sono conformi alla guida di stile.
• Usare i profili di analisi per specificare il set di regole e le condizioni di filtro per le API analizzate. Personalizzare il set di regole di un profilo usando l'estensione centro API Azure per Visual Studio Code.

Limiti

• Attualmente vengono analizzati solo i documenti di specifica OpenAPI e AsyncAPI in formato JSON o YAML.
• Esistono limiti per il numero di profili di analisi e il numero massimo di definizioni api analizzate. L'analisi può richiedere da pochi minuti fino a 24 ore per essere completata.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non è già disponibile, vedere Avvio rapido: Creare il centro API.
• Per personalizzare il set di regole, Visual Studio Code e le estensioni di Visual Studio Code seguenti:
  • Estensione Centro API di Azure per Visual Studio Code
  • Estensione per Visual Studio Code di Spectral

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.

Nel report di analisi api esaminare anche il set di regole usato per l'analisi e la cronologia dei passaggi di linting.

Per visualizzare un riepilogo dell'analisi nel centro API:

1. Nel portale, vai al tuo centro API.

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

   

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.

   

   Suggerimento

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

Gestire i profili di analisi

Azure Centro API usa profili di analisi per l'esecuzione di linting e analisi delle API. Un profilo di analisi specifica un set di regole e, facoltativamente, le condizioni di filtro per le API analizzate. Il profilo di analisi predefinito applica il spectral:oas set di regole a tutte le definizioni OpenAPI e AsyncAPI.

È possibile personalizzare il set di regole e definire le condizioni di filtro nel profilo predefinito oppure creare un nuovo profilo. Ad esempio, è possibile usare un profilo per le API in fase di sviluppo e un altro per le API in produzione.

Per creare un profilo di analisi:

1. Nel portale di Azure passare al centro API.
2. Nel menu a sinistra, in Governance selezionare Analisi> APIGestisci profili> di analisi+ Crea profilo di analisi.
3. Nel riquadro Crea nuovo profilo di analisi immettere un nome e una descrizione per il profilo.
4. In Set di regole viene visualizzato il tipo di analizzatore (motore di linting) per il set di regole. Attualmente è supportato solo Spectral.
5. In Definisci condizioni di filtro aggiungere una o più condizioni di filtro per le definizioni API a cui viene applicato il profilo.
6. Seleziona Crea.

Il profilo viene creato e si prepara una struttura per il set di regole. Per visualizzare il set di regole corrente, selezionare il profilo e nel menu di scelta rapida (...) selezionare Visualizza il set di regole.

Per personalizzare il set di regole, continuare con le sezioni seguenti.

Personalizzare il set di regole del profilo

Usare l'estensione Visual Studio Code per Azure Centro API per personalizzare il set di regole di un profilo. Dopo aver personalizzato il set di regole e testarlo in locale, è possibile distribuirlo di nuovo nel centro API.

1. In Visual Studio Code selezionare l'icona del Centro API di Azure dalla barra attività.
2. Nel riquadro del Centro API, espandere la risorsa del centro API con cui stai lavorando ed espandere Profili.
3. Espandere il profilo da modificare e selezionare ruleset.yaml.
4. Modificare o sostituire il contenuto in base alle esigenze.
5. Salvare le modifiche apportate a ruleset.yaml.

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 la scorciatoia da tastiera CTRL+MAIUSC+P per aprire la Palette comandi.

2. digitare centro API di Azure: seleziona la guida di stile API attiva e premere Invio.

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

   Questo passaggio rende l'insieme di regole personalizzate la guida allo stile delle API attiva per il linting locale.

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).

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. Espandere Profili.
4. Fare clic con il pulsante destro del mouse sul profilo in cui è stato personalizzato il set di regole e scegliere 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 api nel profilo.

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

Contenuto correlato

• Per altre informazioni sul set di regole predefinito, vedere il repository GitHub Spectral.
• Abilitare l'analisi dell’API nel centro API - autogestito