Activer l’analyse des API dans votre centre des API – géré par Microsoft

Cet article explique comment activer l’analyse des API dans Centre API Azure sans avoir à la gérer vous-même (préversion). L’analyse des API offre des fonctionnalités de linting pour analyser les définitions d’API dans le centre des API de votre organisation. Le linting garantit que vos définitions d’API respectent les règles de style organisationnel, en générant des rapports individuels et récapitulatifs. Utilisez l’analyse des API pour identifier et corriger les erreurs et incohérences courantes dans vos définitions d’API.

Important

L’analyse d’API managées dans le Centre API configure automatiquement un moteur de linting et les dépendances nécessaires. Vous pouvez également activer le linting et l’analyse manuellement à l’aide d’une fonction Azure personnalisée. Désactivez n’importe quelle fonction utilisée pour le linting manuel avant d’activer l’analyse d’API managées.

Dans ce scénario :

1. Ajoutez un ensemble de règles de linting (guide de style d’API) dans votre centre API à l’aide de l’extension Visual Studio Code pour Centre API Azure
2. Centre API Azure exécute automatiquement le linting lorsque vous ajoutez ou mettez à jour une définition d’API. Il est également déclenché pour toutes les définitions d’API lorsque vous déployez un ensemble de règles dans votre centre API.
3. Passez en revue les rapports d’analyse des API dans le portail Azure pour voir comment vos définitions d’API sont conformes au guide de style.
4. Personnalisez éventuellement l’ensemble de règles pour les API de votre organisation. Testez l’ensemble de règles personnalisé localement avant de le déployer dans votre centre API.

Limites

• Actuellement, seuls les documents de spécification OpenAPI au format JSON ou YAML sont analysés.
• Par défaut, vous activez l’analyse avec l’ spectral:oasensemble de règles. Pour en savoir plus sur les règles intégrées, consultez le dépôt GitHub Spectre.
• Actuellement, vous configurez un ensemble de règles unique et il est appliqué à toutes les définitions OpenAPI dans votre centre API.
• Les limites suivantes correspondent au nombre maximal de définitions d’API lintées par intervalle de 4 heures :
  • Niveau gratuit : 10
  • Niveau standard : 100

Prérequis

• Un Centre d’API dans votre abonnement Azure. Si vous n’en avez pas encore créé, consultez Démarrage rapide : Créer votre centre d’API.

• Visual Studio Code

• Les extensions Visual Studio Code suivantes :

  • Extension Centre API Azure pour Visual Studio Code

    Important

    Activez l’analyse des API managées à l’aide de la version préliminaire de l’extension du Centre API. Lors de l’installation de l’extension, choisissez la version préliminaire. Basculez entre les versions de mise en production et de préversion à tout moment via le bouton Gérer de l’extension dans la vue Extensions.

  • Extension Spectre pour Visual Studio Code

Activer l’analyse des API à l’aide de Visual Studio Code

Pour activer l’analyse des API à l’aide du jeu de règles de linting par défaut :

1. Dans Visual Studio Code, ouvrez un dossier que vous allez utiliser pour gérer les ensembles de règles pour le Centre API Azure.

2. Sélectionnez l’icône du Centre API Azure dans la barre d’activité.

3. Dans le volet Centre API, développez la ressource du centre API dans laquelle activer l’analyse des API.

4. Cliquez avec le bouton droit sur règles , puis sélectionnez Activer l’analyse des API.

   

Un message vous avertit une fois l’analyse de l’API activée. Un dossier pour votre centre API est créé dans .api-center-rules, à la racine de votre dossier de travail. Le dossier de votre centre API contient :

• Fichier ruleset.yml qui définit le guide de style d’API par défaut utilisé par le moteur de linting.
• Dossier functions avec un exemple de fonction personnalisée que vous pouvez utiliser pour étendre le jeu de règles.

Une fois l’analyse activée, le moteur de linting analyse les définitions d’API dans votre centre API en fonction du jeu de règles par défaut et génère des rapports d’analyse des API.

Voir le rapport d’analyse d’API

Affichez un résumé d’analyse et les rapports d’analyse pour vos définitions d’API dans le portail Azure. Une fois les définitions d’API analysées, les rapports répertorient les erreurs, les avertissements et les informations en fonction du guide de style d’API configuré.

Pour afficher un résumé d’analyse dans votre centre API :

1. Dans le portail, accédez à votre Centre API.

2. Dans le menu de gauche, sous Gouvernance, sélectionnez Analyse d’API. Le récapitulatif s’affiche.

   

3. Sélectionnez éventuellement l’icône Rapport d’analyse des API pour une définition d’API. Le rapport d’analyse des API de définition s’affiche, comme illustré dans la capture d’écran suivante.

   

   Conseil

   Vous pouvez également afficher le rapport d’analyse d’API en sélectionnant analyse dans la barre de menus de la définition d’API.

Personnaliser l’ensemble de règles

Vous pouvez personnaliser l’ensemble de règles par défaut ou le remplacer comme guide de style d’API de votre organisation. Par exemple, vous pouvez étendre le jeu de règles ou ajouter fonctions personnalisées.

Pour personnaliser ou remplacer le jeu de règles :

1. Dans Visual Studio Code, ouvrez le dossier .api-center-rules à la racine de votre dossier de travail.
2. Dans le dossier de la ressource du centre API, ouvrez le fichier ruleset.yml .
3. Modifiez ou remplacez le contenu en fonction des besoins.
4. Enregistrez vos modifications dans ruleset.yml.

Ensemble de règles de test localement

Avant de déployer l’ensemble de règles personnalisé dans votre centre API, validez-le localement. L’extension du Centre API Azure pour Visual Studio Code fournit une prise en charge intégrée du linting des spécifications d’API avec Spectre.

1. Dans Visual Studio Code, utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes.

2. Tapez Centre API Azure : Définir un guide de style d’API actif et appuyez sur Entrée.

3. Choisissez Sélectionnez le fichier local et spécifiez le fichier ruleset.yml que vous avez personnalisé. Appuyez sur Entrée.

   Cette étape rend l’ensemble de règles personnalisé le guide de style d’API actif pour le linting.

À présent, lorsque vous ouvrez un fichier de définition d’API basé sur OpenAPI, une opération de linting locale est automatiquement déclenchée dans Visual Studio Code. Les résultats s’affichent en ligne dans l’éditeur et dans la fenêtre Problèmes (Afficher > Problèmes ou Ctrl+Maj+M).

Passez en revue les résultats de linting. Effectuez les ajustements nécessaires au jeu de règles et continuez à le tester localement jusqu’à ce qu’il effectue la façon dont vous le souhaitez.

Déployer un ensemble de règles dans votre centre API

Pour déployer l’ensemble de règles personnalisé dans votre centre API :

1. Dans Visual Studio Code, sélectionnez l’icône du Centre API Azure dans la barre d’activité.
2. Dans le volet Centre API, développez la ressource du centre API dans laquelle vous avez personnalisé l’ensemble de règles.
3. Cliquez avec le bouton droit sur Règles , puis sélectionnez Déployer des règles dans le Centre API.

Un message vous avertit une fois que les règles sont correctement déployées sur votre centre API. Le moteur de linting utilise l’ensemble de règles mis à jour pour analyser les définitions d’API.

Pour afficher les résultats du linting avec l’ensemble de règles mis à jour, affichez les rapports d’analyse des API dans le portail.

Contenu connexe

• Activer l’analyse des API dans votre centre API – autogéré