Partager via

Activer le linting et l’analyse pour la gouvernance des API dans votre centre d’API

  • Article

Cet article explique comment activer le linting pour analyser les définitions d’API dans le centre d’API de votre organisation pour assurer la conformité aux règles de style d’API de votre organisation. Le linting génère un rapport d’analyse auquel vous pouvez accéder dans votre centre d’API. Utilisez le linting et l’analyse des API pour détecter des erreurs et incohérences courantes dans vos définitions d’API.

Présentation du scénario

Dans ce scénario, vous analysez les définitions d’API dans votre centre d’API à l’aide du moteur de linting open source Spectral. Une application Azure Functions exécute le moteur de linting en réponse aux événements dans votre centre d’API. Spectral vérifie que les API définies dans un document de spécification JSON ou YAML sont conformes aux règles d’un guide de style d’API personnalisable. Un rapport de conformité d’API est généré. Vous pouvez l’afficher dans votre centre d’API.

Le diagramme suivant montre les étapes permettant d’activer le linting et l’analyse dans votre centre d’API.

Diagramme montrant le fonctionnement du linting des API dans le Centre API d’Azure.

  1. Déployer une application Azure Functions qui exécute le moteur de linting Spectral sur une définition d’API.

  2. Configurer un abonnement aux événements dans un centre d’API Azure pour déclencher l’application de fonction.

  3. Un événement est déclenché en ajoutant ou en remplaçant une définition d’API dans le centre d’API.

  4. Lors de la réception de l’événement, l’application de fonction appelle le moteur de linting Spectral.

  5. Le moteur de linting vérifie que les API définies dans la définition sont conformes au guide de style d’API de l’organisation. Il génère ensuite un rapport.

  6. Consulter le rapport d’analyse dans le centre d’API.

Options de déploiement du moteur de linting et de l’abonnement aux événements

Cet article fournit deux options pour déployer le moteur de linting et l’abonnement aux événements dans votre centre d’API :

  • Déploiement automatisé : utilisez Azure Developer CLI (azd) pour le déploiement en une étape de l’infrastructure de linting. Cette option est recommandée pour un processus de déploiement simplifié.

  • Déploiement manuel : suivez les instructions pas à pas pour déployer l’application Azure Functions et configurer l’abonnement aux événements. Cette option est recommandée si vous préférez déployer et gérer les ressources manuellement.

Limites

  • Le linting prend actuellement en charge uniquement des fichiers de spécification JSON ou YAML, tels que les documents de spécification OpenAPI ou AsyncAPI.
  • Par défaut, le moteur de linting utilise le jeu de règles spectral:oas intégré. Pour étendre le jeu de règles ou créer des guides de style d’API personnalisés, consultez le référentiel GitHub pour Spectral.
  • L’application de fonction Azure qui appelle le linting est facturée séparément. C’est vous qui la gérez et l’entretenez.

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.

  • Le fournisseur de ressources Event Grid doit être inscrit dans votre abonnement. Si vous devez inscrire le fournisseur de ressources Event Grid, consultez l’article S’abonner aux événements publiés par un partenaire avec Azure Event Grid.

  • Pour Azure CLI :

    Remarque

    Les commandes az apic nécessitent l’extension Azure CLI apic-extension. Si vous n’avez pas utilisé de commandes az apic, l’extension peut être installée dynamiquement lorsque vous exécutez votre première commande az apic, ou vous pouvez l’installer manuellement. Apprenez-en davantage sur les extensions Azure CLI.

    Pour connaître les dernières modifications et mises à jour relatives à apic-extension, consultez les notes de publication.

    Remarque

    Les exemples de commandes Azure CLI de cet article peuvent s’exécuter dans PowerShell ou dans un interpréteur de commandes bash. Si c’est nécessaire en raison d’une syntaxe de variables différente, des exemples distincts de commandes sont fournis pour les deux interpréteurs de commandes.

Déploiement azd de l’application Azure Functions et de l’abonnement aux événements

Cette section fournit des étapes automatisées utilisant Azure Developer CLI pour configurer l’application Azure Functions et l’abonnement aux événements qui activent le linting et l’analyse dans votre centre d’API. Vous pouvez également configurer les ressources manuellement.

Autres prérequis pour cette option

Exécuter l’exemple en utilisant azd

  1. Clonez le référentiel GitHub et ouvrez-le dans Visual Studio Code.

  2. Basculez sur le dossier APICenter-Analyzer dans le dépôt.

  3. Dans le dossier resources/rulesets se trouve un fichier oas.yaml. Ce fichier représente votre guide de style d’API actuel. Il peut être modifié en fonction des besoins et des exigences de votre organisation.

  4. Authentifiez-vous dans Azure Developer CLI et Azure CLI avec les commandes suivantes :

    azd auth login

az login

  5. Exécutez la commande suivante pour déployer l’infrastructure de linting sur votre abonnement Azure.

    azd up

  6. Suivez les invites pour fournir les informations et les paramètres de déploiement nécessaires, comme le nom de l’environnement et le nom du centre d’API. Pour plus d’informations, consultez Exécution de l’exemple avec Azure Developer CLI (azd).

    Remarque

    Le déploiement peut prendre quelques minutes.

  7. Une fois le déploiement effectué, accédez à votre centre d’API dans le portail Azure. Dans le menu de gauche, sélectionnez Événements>Abonnements aux événements pour voir l’abonnement aux événements qui a été créé.

Vous pouvez maintenant charger un fichier de définition d’API dans votre centre d’API pour déclencher l’abonnement aux événements et exécuter le moteur de linting.

Étapes manuelles pour configurer l’application Azure Functions et l’abonnement aux événements

Cette section fournit les étapes de déploiement manuelles pour configurer l’application Azure Functions et l’abonnement aux événements qui activent le linting et l’analyse dans votre centre d’API. Vous pouvez également utiliser Azure Developer CLI pour le déploiement automatisé.

Autres prérequis pour cette option

Étape 1. Déployer sur votre application Azure Functions

Pour déployer l’application Azure Functions qui exécute la fonction de linting sur les définitions d’API :

  1. Clonez le référentiel GitHub et ouvrez-le dans Visual Studio Code.

  2. Dans le dossier resources/rulesets se trouve un fichier oas.yaml. Ce fichier représente votre guide de style d’API actuel. Il peut être modifié en fonction des besoins et des exigences de votre organisation.

  3. Si vous le souhaitez, exécutez localement l’application de fonction pour la tester. Pour plus d’informations sur l’utilisation de l’API, consultez le fichier LISEZ-MOI dans le référentiel.

  4. Déployez l’application de fonction dans Azure. Pour voir les étapes, consultez Démarrage rapide : Créer une fonction dans Azure avec TypeScript à l’aide de Visual Studio Code.

    Remarque

    Il se peut que le déploiement de l’application de fonction prenne quelques minutes.

  5. Connectez-vous au Portail Azure et accédez à l’application de fonction.

  6. Sur la page Présentation, vérifiez les détails suivants :

    • Confirmez que l’État de l’application de fonction est En cours d’exécution.
    • Sous Fonctions, confirmez que le l’État de la fonction apicenter-analyzer est Activé.

    Capture d’écran de l’application de fonction dans le portail.

Étape 2. Configurer votre identité managée dans votre application de fonction

Pour permettre à l’application de fonction d’accéder au centre d’API, configurez une identité managée pour l’application de fonction. Les étapes suivantes montrent comment activer et configurer une identité managée affectée par le système pour l’application de fonction à l’aide du Portail Azure ou d’Azure CLI.

  1. Dans le Portail Azure, accédez à votre application de fonction et sélectionnez Identité sous la section Paramètres.
  2. Sous l’onglet Attribué par le système, définissez l’État sur Activé, puis sélectionnez Enregistrer.

Maintenant que l’identité managée est activée, attribuez-lui le rôle Gestionnaire de conformité du Centre API d’Azure pour accéder au Centre API.

  1. Dans le portail Azure, accédez à votre Centre API et sélectionnez Contrôle d’accès (IAM).
  2. Sélectionnez + Ajouter > Ajouter une attribution de rôle.
  3. Sélectionnez Rôles de fonction de travail, puis sélectionnez Gestionnaire de conformité du Centre API d’Azure. Cliquez sur Suivant.
  4. Dans l’onglet Membres, sous Affecter l’accès à, sélectionnez Identité managée >+ Sélectionner des membres.
  5. Dans la page Sélectionner des identités managées, recherchez et sélectionnez l’identité managée de l’application de fonction. Cliquez sur Sélectionner puis sur Suivant.
  6. Vérifiez l'attribution du rôle, puis sélectionnez Vérifier + attribuer.

Étape 3. Configurer l’abonnement aux événements dans votre centre d’API

Maintenant, créez un abonnement aux événements dans votre centre d’API pour déclencher l’application de fonction lorsqu’un fichier de définition d’API est chargé ou mis à jour. Les étapes suivantes montrent comment créer l’abonnement aux événements à l’aide du Portail Azure ou d’Azure CLI.

  1. Dans le portail Azure, accédez à votre Centre API, puis sélectionnez Événements.

  2. Sous l’onglet Démarrage, sélectionnez Fonction Azure.

  3. Dans la page Créer un abonnement aux événements, effectuez les actions suivantes :

    1. Entrez un Nom descriptif pour l’abonnement aux événements et sélectionnez Schéma Event Grid.

    2. Dans Détails de sujet, entrez le Nom de sujet système de votre choix.

    3. Dans Types d’événements, sélectionnez les événements suivants :

      • Définition d’API ajoutée
      • Définition d’API mise à jour

    4. Dans Détails des points de terminaison, sélectionnez Fonction Azure > Configurer un point de terminaison.

    5. Dans la page Sélectionner la fonction Azure, sélectionnez l’application de fonction et la fonction apicenter-linter que vous avez configurée. Cliquez sur Confirmer la sélection.

    6. Sélectionnez Créer.

      Capture d’écran de la création de l’abonnement aux événements dans le portail.

  4. Sélectionnez l’onglet Abonnements aux événements et sélectionnez Actualiser. Confirmez que l’État d'approvisionnement de l’abonnement aux événements est à l’état de Réussite.

    Capture d’écran de l’état de l’abonnement aux événements dans le portail.

Remarque

Il se peut que l’abonnement à l’événement prenne un peu de temps pour se propager vers l’application de fonction.

Déclencher un événement dans votre centre d’API

Pour tester l’abonnement aux événements, essayez de charger ou de mettre à jour un fichier de définition d’API associé à une version d’API dans votre centre d’API. Par exemple, chargez un document OpenAPI ou AsyncAPI. Une fois l’abonnement à l’événement déclenché, l’application de fonction appelle le moteur de linting d’API pour analyser la définition de l’API.

Pour confirmer que l’abonnement à l’événement a été déclenché :

  1. Accédez à votre centre d’API et sélectionnez Événements dans le menu de gauche.

  2. Sélectionnez l’onglet Abonnements aux événements, puis sélectionnez l’abonnement aux événements pour votre application de fonction.

  3. Passez en revue les métriques pour vérifier que l’abonnement aux événements a été déclenché et que le linting a bien été appelé.

    Capture d’écran des métriques de l’abonnement aux événements dans le portail.

    Remarque

    Il se peut que l’affichage des métriques prenne quelques minutes.

Après avoir analysé la définition de l’API, le moteur de linting génère un rapport basé sur le guide de style d’API configuré.

Voir le rapport d’analyse d’API

Vous pouvez voir le rapport d’analyse de votre définition d’API dans le portail Azure. Après l’analyse d’une définition d’API, le rapport liste les erreurs et les informations basées sur le guide de style d’API configuré.

Dans le portail, vous pouvez également voir un récapitulatif des rapports d’analyse pour toutes les définitions d’API de votre centre d’API.

Rapport d’analyse pour une définition d’API

Pour voir le rapport d’analyse d’une définition d’API dans votre centre d’API :

  1. Dans le portail, accédez à la version de l’API dans votre Centre API où vous avez ajouté ou mis à jour une définition d’API.
  2. Dans le menu de gauche, sous Détails, sélectionnez Définitions.
  3. Sélectionnez la définition d’API que vous avez chargée ou mise à jour.
  4. Sélectionnez l'onglet Analyse. Capture d’écran de l’onglet Analyse pour la définition d’API dans le portail.

Le Rapport d’analyse de l’API s’ouvre et affiche la définition, les erreurs, les avertissements et les informations de l’API en fonction du guide de style d’API configuré. La capture d’écran suivante affiche un exemple de rapport d’analyse d’API.

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

Récapitulatif de l’analyse d’API

Pour voir un récapitulatif des rapports d’analyse pour toutes les définitions d’API de votre centre d’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.

Contenu connexe

En savoir plus sur Event Grid :