Partager via

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

  • Article

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. Les définitions d'API sont analysées par défaut avec un jeu de règles spectral:oas (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.
  • Vous pouvez utiliser l’extension Centre d’API Azure pour Visual Studio Code pour personnaliser et tester votre propre guide de style d’API localement, puis la déployer dans votre centre d’API.

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.
  • Actuellement, vous configurez un ensemble de règles unique et il est appliqué à toutes les définitions OpenAPI dans votre centre API.
  • Le nombre maximal de définitions d’API analysées est soumis à des limites. 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.

Personnaliser l’ensemble de règles

Vous pouvez utiliser l'extension API Center pour Visual Studio Code afin de personnaliser le jeu de règles par défaut de votre centre d'API ou le remplacer par le guide de style des 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, sélectionnez l’icône du Centre API Azure dans la barre d’activité.
  2. Ouvrez le dossier .api-center-rules à la racine de votre dossier de travail.
  3. Dans le dossier de la ressource de votre centre API, ouvrez le fichier ruleset.yml.
  4. Modifiez ou remplacez le contenu en fonction des besoins.
  5. 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).

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 de l’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. 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