Bien démarrer avec l’extension Centre API Azure pour Visual Studio Code (préversion)
Pour créer, découvrir, essayer et consommer des API dans votre centre API, vous pouvez utiliser l’extension Centre API Azure dans votre environnement de développement Visual Studio Code :
Créer des API : mettez les API que vous créez à la disposition des autres utilisateurs en les inscrivant dans votre centre API. Effectuez un « shift left » des vérifications de conformité de conception d’API dans Visual Studio Code avec la prise en charge intégrée du linting. Assurez-vous que les nouvelles versions d’API n’interrompent pas les consommateurs d’API avec la détection des changements cassants.
Découvrir les API : parcourez les API dans votre centre API et examinez-en les détails et la documentation.
Essayer les API : utilisez l’interface utilisateur Swagger ou le client REST pour explorer les requêtes et réponses d’API.
Consommer les API : générez des clients SDK d’API pour le langage de votre choix, par exemple JavaScript, TypeScript, .NET, Python ou Java, en utilisant le moteur Microsoft Kiota qui génère des kits SDK pour Microsoft Graph, GitHub, etc.
Remarque
L’extension Centre d’API Azure pour Visual Studio Code est en préversion. Découvrez plus en détail la préversion de l’extension.
Prérequis
Un ou plusieurs centres d’API dans votre abonnement Azure. Si vous n’en avez pas encore créé, consultez Démarrage rapide : Créer votre centre d’API.
Pour l’heure, vous devez disposer du rôle Contributeur ou d’autorisations supérieures pour pouvoir accéder aux centres API avec l’extension.
Les extensions Visual Studio Code suivantes sont facultatives et nécessaires uniquement dans certains scénarios, comme indiqué :
- Extension du client REST : pour envoyer des requêtes HTTP et voir directement les réponses dans Visual Studio Code
- Extension Microsoft Kiota : pour générer des clients d’API
- Extension spectrale - pour exécuter des vérifications de conformité de conception d'API avec décalage gauche dans Visual Studio Code
- Optic CLI : pour détecter les changements cassants entre les documents de spécification d’API
Programme d’installation
- Installez l’extension Centre API Azure pour Visual Studio Code à partir de la Place de marché Visual Studio Code. Installez les extensions facultatives, si nécessaire.
- Dans Visual Studio Code, dans la barre d’activités à gauche, sélectionnez API Center (Centre API).
- Si vous n’êtes pas connecté à votre compte Azure, sélectionnez Sign in to Azure... (Se connecter à Azure), puis suivez les invites pour vous connecter. Sélectionnez un compte Azure avec le ou les centres API à partir desquels vous souhaitez voir les API. Vous pouvez également filtrer sur des abonnements spécifiques si vous en avez un grand nombre à voir.
Inscrire les API
Inscrivez une API dans votre centre API directement à partir de Visual Studio Code, soit en l’inscrivant en une seule opération soit avec un pipeline CI/CD.
- Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : inscrire une API et appuyez sur Entrée.
- Indiquez comment vous souhaitez inscrire l’API dans votre centre API :
- Pas à pas est la méthode idéale pour inscrire des API en une seule fois.
- CI/CD est une méthode qui ajoute un pipeline GitHub ou Azure DevOps préconfiguré à votre espace de travail Visual Studio Code actif. Elle s’exécute dans le cadre d’un flux de travail CI/CD à chaque commit au niveau du contrôle de code source. Il est recommandé d’inventorier les API dans le centre API à l’aide de la méthode CI/CD pour faire en sorte que les métadonnées d’API, notamment la spécification et la version, restent à jour dans votre centre API, à mesure que les API évoluent au fil du temps.
- Effectuez les étapes d’inscription :
- Pour la méthode pas à pas, sélectionnez le centre API dans lequel inscrire les API, puis répondez aux invites en indiquant notamment le titre, le type, la phase du cycle de vie, la version et la spécification des API à inscrire.
- Pour la méthode CI/CD, sélectionnez GitHub ou Azure DevOps, en fonction du mécanisme de contrôle de code source que vous utilisez. Un espace de travail Visual Studio Code doit être ouvert pour que l’extension Centre d’API Azure puisse ajouter un pipeline à votre espace de travail. Une fois le fichier ajouté, effectuez les étapes décrites dans le fichier de pipeline CI/CD lui-même pour configurer l’identité et les variables d’environnement du pipeline Azure/de l’action GitHub. Dès l’envoi (push) au contrôle de code source, l’API est inscrite dans votre centre API.
Conformité de conception d’API
Pour garantir que les API que vous créez sont conformes aux standards de conception organisationnels, l’extension Centre API Azure pour Visual Studio Code offre une prise en charge intégrée du linting de spécification d’API avec Spectral.
- Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : Définir un guide de style d’API actif et appuyez sur Entrée.
- Sélectionnez l’une des règles par défaut proposées ou, si votre organisation dispose déjà d’un guide de style, utilisez Select Local File (Sélectionner un fichier local) ou Input Remote URL (Entrer une URL distante) pour spécifier l’ensemble de règles actif dans Visual Studio Code. Appuyez sur Entrée.
Du moment qu’un guide de style d’API est défini, le fait d’ouvrir un fichier de spécification OpenAPI ou AsyncAPI a pour effet de déclencher une opération de linting locale dans Visual Studio Code. Les résultats s’affichent à la fois dans l’éditeur et dans la fenêtre Problems (Problèmes) (View (Afficher) >Problems (Problèmes) ou Ctrl+Maj+M).
Détection de changement cassant
Lors de l’introduction de nouvelles versions de votre API, il est important de vous assurer que les modifications effectuées n’interrompent pas les consommateurs d’API utilisant des versions précédentes de votre API. L’extension Azure API Center pour Visual Studio Code facilite ce processus grâce à la détection de changements cassants pour les documents de spécification OpenAPI alimentés par Optic.
- Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Azure API Center : détecter les changements cassants et appuyez sur Entrée.
- Sélectionnez le premier document de spécification d’API à comparer. Les options valides peuvent inclure des spécifications d’API trouvées dans votre centre d’API, un fichier local ou l’éditeur actif dans Visual Studio Code.
- Sélectionnez le deuxième document de spécification d’API à comparer. Les options valides peuvent inclure des spécifications d’API trouvées dans votre centre d’API, un fichier local ou l’éditeur actif dans Visual Studio Code.
Visual Studio Code ouvre un aperçu des différences entre les deux spécifications de l’API. Tous les changements cassants sont affichés à la fois inlined et dans l’éditeur, ainsi que dans la fenêtre Problèmes (Afficher>Problèmes ou Ctrl+Maj+M).
API de découverte
Les ressources de votre centre API apparaissent dans l’arborescence de gauche. Développez une ressource du centre API pour afficher les API, les versions, les définitions, les environnements et les déploiements.
Recherchez des API dans un Centre d’API à l’aide de l’icône de recherche affichée dans l’élément d’arborescence Apis.
Consulter la documentation d’API
Vous pouvez consulter la documentation relative à une définition d’API dans votre centre API et essayer des opérations d’API. Cette fonctionnalité n’est disponible que pour les API OpenAPI de votre centre API.
Développez l’arborescence Centre API pour afficher une définition d’API.
Cliquez avec le bouton droit sur la définition, puis sélectionnez Open API Documentation (Ouvrir la documentation d’API). Un nouvel onglet s’affiche avec l’interface utilisateur Swagger pour la définition d’API.
Pour essayer l’API, sélectionnez un point de terminaison, sélectionnez Try it out (Essayer), entrez les paramètres obligatoires, puis sélectionnez Execute (Exécuter).
Remarque
Selon l’API, vous serez peut-être amené à fournir des informations d’identification d’autorisation ou une clé API pour pouvoir essayer l’API.
Générer un fichier HTTP
Vous pouvez afficher un fichier .http basé sur la définition d’API dans votre centre API. Si l’extension Client REST est installée, vous pouvez effectuer des requêtes directement à partir de l’éditeur Visual Studio Code. Cette fonctionnalité n’est disponible que pour les API OpenAPI de votre centre API.
Développez l’arborescence Centre API pour afficher une définition d’API.
Cliquez avec le bouton droit sur la définition, puis sélectionnez Generate HTTP File (Générer un fichier HTTP). Un nouvel onglet s’affiche avec un document .http rempli par la spécification d’API.
Pour effectuer une requête, sélectionnez un point de terminaison, puis sélectionnez Send Request (Envoyer la requête).
Remarque
Selon l’API, vous serez peut-être amené à fournir des informations d’identification d’autorisation ou une clé API pour pouvoir effectuer la requête.
Générer un client d’API
Utilisez l’extension Microsoft Kiota pour générer un client d’API pour votre langage préféré. Cette fonctionnalité n’est disponible que pour les API OpenAPI de votre centre API.
- Développez l’arborescence Centre API pour afficher une définition d’API.
- Cliquez avec le bouton droit sur la définition, puis sélectionnez Generate API Client (Générer un client d’API). Le volet Kiota OpenAPI Generator s’affiche.
- Sélectionnez les points de terminaison d’API et les opérations HTTP que vous souhaitez inclure dans vos kits SDK.
- Sélectionnez Generate API client (Générer un client d’API).
Entrez des détails de configuration à propos du nom, de l’espace de noms et du répertoire de sortie du kit SDK.
Sélectionnez le langage pour le SDK généré.
Le client est généré.
Pour plus d’informations sur l’utilisation de l’extension Kiota, consultez Extension Microsoft Kiota pour Visual Studio Code.