Partager via

Activer et afficher le catalogue d’API de plateforme Centre API Azure

  • Article

Cet article explique comment fournir aux développeurs d’entreprise l’accès au catalogue d’API de plateforme Centre API Azure (préversion) dans l’extension Visual Studio Code pour Centre API Azure. À l’aide du catalogue d’API de plateforme, les développeurs peuvent découvrir des API dans votre centre d’API Azure, afficher les définitions d’API et éventuellement générer des clients d’API lorsqu’ils n’ont pas d’accès leur permettant de gérer le centre d’API lui-même ou ajouter des API à l’inventaire. L’accès au catalogue d’API de plateforme est géré à l’aide de Microsoft Entra ID et du contrôle d’accès en fonction du rôle Azure.

Conseil

L’extension Visual Studio Code fournit davantage de fonctionnalités aux développeurs d’API disposant d’autorisations de gestion d’un centre API Azure. Par exemple, les développeurs d’API peuvent inscrire des API dans le centre API directement ou à l’aide de pipelines CI/CD. En savoir plus

Prérequis

Pour les administrateurs du centre d’API

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

  • Autorisations pour créer une inscription d'application dans un locataire Microsoft Entra associé à votre abonnement Azure et autorisations pour accorder l'accès aux données de votre centre API.

Pour les développeurs d’applications

  • Extension Centre API Azure pour Visual Studio Code

    Important

    Actuellement, l’accès au catalogue d’API de plateforme est disponible uniquement dans la version préliminaire de l’extension. Lors de l’installation de l’extension à partir de la Place de marché Visual Studio Code, vous pouvez choisir d’installer la version de mise en production ou une version préliminaire. Basculez entre les deux versions à tout moment à l’aide du menu contextuel Gérer du bouton Gérer de l’extension, dans la vue Extensions.

Les extensions Visual Studio Code suivantes est facultative :

Étapes pour permettre aux administrateurs du centre d’API d’activer l’accès au catalogue

Les sections suivantes fournissent des étapes afin que les administrateurs du centre d’API puissent permettre aux développeurs d’entreprise d’accéder au catalogue d’API de plateforme.

Créer l'enregistrement de l'application Microsoft Entra

Configurez d’abord une inscription d’application dans votre tenant Microsoft Entra ID. L’inscription de l’application permet à l’extension Visual Studio Code pour Centre API Azure d’accéder au catalogue d’API de plateforme pour le compte d’un utilisateur connecté.

  1. Dans le Portail Microsoft Azure, accédez aux inscriptions d’application>Microsoft Entra ID.

  2. Sélectionnez + Nouvelle inscription.

  3. Sur la page Inscrire une application, définissez les valeurs comme suit :

    • Définissez le Nom sur un nom explicite tel que platform-api-catalog
    • Sous Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel (locataire unique).
    • Dans URI de redirection, sélectionnez Application monopage (SPA) et définissez l’URI sur l’URI du runtime de votre centre d’API. Par exemple : https://<service name>.data.<region>.azure-apicenter.ms. Exemple : https://contoso-apic.data.eastus.azure-apicenter.ms.
    • Sélectionnez Inscrire.

    Conseil

    Vous pouvez utiliser la même inscription d’application pour accéder à d’autres centres d’API. Dans URI de redirection, continuez à ajouter des URI de redirection pour d’autres centres d’API que vous souhaitez afficher dans le catalogue d’API de plateforme.

  4. Dans la page Vue d’ensemble, copiez l’ID d’application (client) et l’ID d’annuaire (locataire). Vous définissez ces valeurs ultérieurement lorsque vous vous connectez au centre d’API à partir de l’extension Visual Studio Code.

  5. Dans le menu de gauche, sous Gérer, sélectionnez Authentification>+ Ajouter une plateforme.

  6. Dans la page Configurer des plateformes, sélectionnez Applications mobiles et de bureau.

  7. Dans la page Configurer Bureau + appareils, entrez l’URI de redirection suivant, puis sélectionnez Configurer :

    https://vscode.dev/redirect

  8. Dans le menu de gauche, sous Gérer, sélectionnez Autorisations d’API>+ Ajouter une autorisation.

  9. Dans la page Demander des autorisations d’API, procédez comme suit :

    1. Sélectionnez l’onglet API utilisées par mon organisation.
    2. Recherchez et sélectionnez Azure API Center. Vous pouvez également rechercher et sélectionner l'ID de l'application c3ca1a77-7a87-4dba-b8f8-eea115ae4573.
    3. Sur la page Sélectionner des autorisations, sélectionnez user_impersonation.
    4. Sélectionnez Ajouter des autorisations.

    Les autorisations Azure API Center apparaissent sous Autorisations configurées.

    Capture d’écran des autorisations requises dans l’inscription de l’application Microsoft Entra ID dans le portail.

Activer la connexion au catalogue d’API de plateforme par les utilisateurs et groupes Microsoft Entra

Les développeurs d’entreprise doivent se connecter avec un compte Microsoft pour voir le catalogue d’API de plateforme de votre centre d’API. Si nécessaire, ajouter ou inviter des développeurs à votre tenant Microsoft Entra.

Ensuite, pour activer la connexion, attribuez le rôle Lecteur de données du Centre API Azure aux utilisateurs ou aux groupes de votre tenant, limités à votre centre d’API.

Important

Par défaut, vous et les autres administrateurs du centre d’API n'avez pas accès aux API dans le catalogue d’API de plateforme de l’extension Centre API. Assurez-vous d’attribuer le rôle Azure API Center Data Reader à vous-même et aux autres administrateurs.

Pour connaître les conditions préalables détaillées et les étapes permettant d'attribuer un rôle aux utilisateurs et aux groupes, consultez Attribuer des rôles Azure à l'aide du Portail Microsoft Azure. De brèves étapes suivent :

  1. Dans le Portail Microsoft Azure, accédez à votre centre API.
  2. Dans le menu de gauche, sélectionnez Contrôle d'accès (IAM)>+ Ajouter une attribution de rôle.
  3. Dans le volet Ajouter une attribution de rôle, définissez les valeurs comme suit :
    • Sur la page Rôle, recherchez et sélectionnez Azure API Center Data Reader. Cliquez sur Suivant.
    • Sur la page Membres, dans Attribuer l'accès à, sélectionnez Utilisateur, groupe ou principal de service>+ Sélectionner les membres.
    • Sur la page Sélectionner les membres, recherchez et sélectionnez les utilisateurs ou les groupes auxquels attribuer le rôle. Cliquez sur Sélectionner puis sur Suivant.
    • Vérifiez l'attribution du rôle, puis sélectionnez Vérifier + attribuer.
  4. Répétez les étapes précédentes pour activer la connexion au catalogue d’API de plateforme pour d’autres centres d’API.

Remarque

Pour rationaliser la configuration de l'accès pour les nouveaux utilisateurs, nous vous recommandons d'attribuer le rôle à un groupe Microsoft Entra et de configurer une règle d'appartenance à un groupe dynamique. Pour en savoir plus, consultez Créer ou mettre à jour un groupe dynamique dans Microsoft Entra ID.

Étapes permettant aux développeurs d’entreprise d’accéder au catalogue d’API de plateforme

Les développeurs peuvent suivre ces étapes pour se connecter afin d’afficher un catalogue d’API de plateforme à l’aide de l’extension Visual Studio Code. Les paramètres de connexion au centre d’API doivent être fournis par l’administrateur du centre d’API.

Se connecter à un centre d’API

  1. Installez la version préliminaire de l’extension du Centre API Azure pour Visual Studio Code pour Visual Studio Code.

  2. Dans Visual Studio Code, dans la barre d’activités à gauche, sélectionnez API Center (Centre API).

    Capture d’écran de l’icône Centre API dans la barre d’activité.

  3. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : Se connecter à un centre d’API et appuyez sur Entrer.

  4. Répondez aux invites pour entrer les informations suivantes :

    1. URL du runtime de votre centre d’API, au format <service name>.data.<region>.azure-apicenter.ms (sans préfixe https://). Exemple : contoso-apic.data.eastus.azure-apicenter.ms. Cette URL de runtime s’affiche dans la page Vue d’ensemble du centre d’API dans le Portail Azure.
    2. ID d’application (client) à partir de l’inscription de l’application configurée par l’administrateur dans la section précédente.
    3. ID de répertoire (tenant) à partir de l’inscription de l’application configurée par l’administrateur dans la section précédente.

    Conseil

    Un administrateur du centre d’API doit fournir ces détails de connexion aux développeurs ou fournir un lien direct au format suivant :
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    Une fois que vous vous êtes connecté au centre d’API, le nom du centre d’API apparaît dans le catalogue d’API de plateforme du Centre API.

  5. Pour afficher les API dans le centre d’API, sous le nom du centre d’API, sélectionnez Se connecter à Azure. La connexion est autorisée avec un compte Microsoft affecté au rôle Lecteur de données du Centre API Azure dans le centre d’API.

    Capture d’écran du catalogue d’API de plateforme du Centre API dans l’extension VS Code.

  6. Après vous être connecté, sélectionnez API pour répertorier les API dans le centre d’API. Développez une API pour explorer ses versions et définitions.

    Capture d’écran du catalogue d’API de plateforme du Centre API avec des API dans l’extension VS Code.

  7. Répétez les étapes précédentes pour vous connecter à d’autres centres d’API, si l’accès est configuré.

Découvrir et consommer des API dans le catalogue

Le catalogue d’API de plateforme aide les développeurs d’entreprise à découvrir les détails de l’API et à démarrer le développement du client d’API. Les développeurs peuvent accéder aux fonctionnalités suivantes en faisant un clic droit sur une définition d’API dans le catalogue d’API de plateforme :

  • Document de spécification de l’API d’exportation : exporter une spécification d’API à partir d’une définition, puis la télécharger en tant que fichier
  • Générer un client d’API : utiliser l’extension Microsoft Kiota pour générer un client d’API pour leur langage préféré
  • Générer Markdown : générer la documentation de l’API au format Markdown
  • Documentation OpenAPI : consulter la documentation d’une définition d’API et essayer les opérations dans une interface utilisateur Swagger (disponible uniquement pour les définitions OpenAPI)

Dépannage

Dans certaines conditions, un utilisateur peut rencontrer le message d’erreur suivant après la connexion au catalogue d’API de plateforme du Centre API et en développant la liste des API pour un centre d’API :

Error: Cannot read properties of undefined (reading 'nextLink')

Vérifiez que l’utilisateur dispose du rôle Lecteur de données du Centre API Azure dans le centre d’API. Si nécessaire, réattribuez le rôle à l’utilisateur. Actualisez ensuite le catalogue d’API de plateforme du Centre API dans l’extension Visual Studio Code.

Impossible de se connecter à Azure

Si les utilisateurs auxquels le rôle Lecteur de données du Centre API Azure a été attribué ne peuvent pas terminer le flux de connexion après avoir sélectionné Se connecter à Azure dans le catalogue d’API de plateforme, il peut y avoir un problème avec la configuration de la connexion.

Vérifiez les paramètres de l’inscription de l’application que vous avez configurée dans Microsoft Entra ID. Vérifiez les valeurs de l’ID d’application (client) et de l’ID de répertoire (tenant) dans l’inscription de l’application et l’URL de runtime du centre d’API. Ensuite, configurez à nouveau la connexion au centre d’API.

Impossible de sélectionner les autorisations Centre API Azure dans l’inscription de l’application Microsoft Entra ID

Si vous ne parvenez pas à demander des autorisations API à Azure API Center lors de l'inscription de votre application Microsoft Entra pour le portail API Center, vérifiez que vous recherchez Azure API Center (ou l'ID d'application c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Si l'application n'est pas présente, il peut y avoir un problème avec l'enregistrement du fournisseur de ressources Microsoft.ApiCenter dans votre abonnement. Vous devrez peut-être réenregistrer le fournisseur de ressources. Pour ce faire, exécutez la commande suivante dans Azure CLI :

az provider register --namespace Microsoft.ApiCenter

Après avoir réenregistré le fournisseur de ressources, réessayez de demander les autorisations API.

Contenu connexe