Analyser les API dans votre centre d’API – Managé par Microsoft

Le centre d’API de votre organisation inclut des fonctionnalités intégrées de linting managées par Microsoft (préversion) pour analyser les définitions d’API afin de vérifier leur conformité aux règles de style organisationnelles, en générant à la fois des rapports individuels et des rapports récapitulatifs. L’analyse des API identifie et vous aide à corriger les erreurs et incohérences courantes dans vos définitions d’API.

Avec l’analyse des API :

  • Azure API Center analyse automatiquement vos définitions d’API chaque fois que vous ajoutez ou mettez à jour une définition d’API. Le linting de vos définitions d’API est effectué par défaut avec un spectral:oas ensemble de règles (guide de style d’API).
  • Les rapports d’analyse des API sont générés dans le portail Azure, montrant comment vos définitions d’API sont conformes au guide de style.
  • Utilisez des profils d’analyse pour spécifier l’ensemble de règles et les conditions de filtre pour les API analysées. Personnalisez l'ensemble de règles d'un profil à l'aide de l'extension du Centre d'API Azure pour Visual Studio Code.

Important

Si vous le préférez, vous pouvez activer l'analyse et le linting autogérés à l’aide d’une fonction Azure personnalisée, en remplaçant les fonctionnalités intégrées. Désactivez n’importe quelle fonction utilisée pour le linting autogéré avant d’utiliser l’analyse de l’API managée.

Limites

  • Actuellement, seuls les documents de spécification OpenAPI et AsyncAPI au format JSON ou YAML sont analysés.
  • Il existe des limites pour le nombre de profils d’analyse et le nombre maximal de définitions d’API analysées. La durée de l’analyse peut varier de quelques minutes à 24 heures.

Prérequis

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

Dans le rapport d’analyse de l’API, examinez également le jeu de règles utilisé pour l'analyse ainsi que l'historique des passages de linting.

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.

    Capture d’écran du résumé de l’analyse d’API dans le portail.

  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.

    Capture d’écran d’un rapport d’analyse d’API dans le portail.

    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.

Gérer les profils d’analyse

Azure Centre d’API utilise des profils analysis pour le linting et l’analyse des API. Un profil d’analyse spécifie un ensemble de règles et filtre éventuellement des conditions pour les API analysées. Le profil d’analyse par défaut applique l’ensemble spectral:oas de règles à toutes les définitions OpenAPI et AsyncAPI.

Vous pouvez personnaliser l’ensemble de règles et définir des conditions de filtre dans le profil par défaut, ou créer un profil. Par exemple, vous pouvez utiliser un profil pour les API en cours de développement et une autre pour les API en production.

Note

Dans le plan Standard du Centre d’API, vous pouvez créer jusqu’à trois profils d’analyse. Un seul profil est pris en charge dans le plan Gratuit.

Pour créer un profil d’analyse :

  1. Dans le portail Azure, accédez à votre centre d’API.
  2. Dans le menu de gauche, sous Gouvernance, sélectionnez API Analysis>Manage analysis profiles>+ Create analysis profile( Créer un profil d’analyse).
  3. Dans le volet Créer un profil d’analyse , entrez un nom et une description pour le profil.
  4. Dans Ruleset, le type d’analyseur (moteur de linting) du jeu de règles s’affiche. Actuellement, seul Spectral est pris en charge.
  5. Sous Définir des conditions de filtre, ajoutez une ou plusieurs conditions de filtre pour les définitions d’API auxquelles le profil est appliqué.
  6. Sélectionnez Créer.

Capture d’écran de la création d’un profil d’analyse dans le portail.

Le profil est créé et un scaffold de règles est créé. Pour afficher l’ensemble de règles actuel, sélectionnez le profil, puis, dans le menu contextuel (...) , sélectionnez Afficher l’ensemble de règles.

Pour personnaliser l’ensemble de règles, passez aux sections suivantes.

Personnaliser l’ensemble de règles du profil

Utilisez l'extension Visual Studio Code pour Azure Centre d'API pour personnaliser l'ensemble de règles d'un profil. Après avoir personnalisé l’ensemble de règles et testé localement, vous pouvez le déployer dans votre centre d’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 d’API, développez la ressource du Centre d’API avec laquelle vous travaillez, puis développez Profils.
  3. Développez le profil que vous souhaitez modifier, puis sélectionnez ruleset.yaml.
  4. Modifiez ou remplacez le contenu en fonction des besoins.
  5. Enregistrez vos modifications dans ruleset.yaml.

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.yaml 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 local.

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

Conseil

Les développeurs d’API de votre organisation peuvent également utiliser cette fonctionnalité de linting locale pour améliorer leurs définitions d’API avant d’inscrire des API dans votre centre d’API.

Capture d’écran du linting d’une définition d’API dans Visual Studio Code.

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. Développez Profils.
  4. Cliquez avec le bouton droit sur le profil dans lequel vous avez personnalisé l’ensemble de règles, puis sélectionnez Déployer des règles dans le Centre des 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 dans le profil.

Pour consulter les résultats du linting avec les règles mises à jour, consultez les rapports d’analyse des API dans le portail.

Contenu connexe

  • Last updated on