Héberger automatiquement votre portail du Centre d’API

Cet article explique comment héberger automatiquement le portail du Centre d’API, un site web que les développeurs et d’autres parties prenantes de votre organisation peuvent utiliser pour découvrir les API de votre centre d’API. Déployez une implémentation de référence du portail à partir du référentiel de démarrage du portail du Centre d’API .

À propos de l’auto-hébergement du portail

Vous pouvez générer et déployer une implémentation de référence du portail à l’aide du code dans le référentiel API Center portal starter. Le portail utilise l’API du plan de données du Centre d’API Azure pour récupérer des données à partir de votre centre d’API.

L’implémentation de référence du portail du Centre d’API fournit les éléments suivants :

• Infrastructure pour la publication et la gestion d’un portail d’API géré par le client à l’aide de GitHub Actions
• Plateforme portail que les clients peuvent modifier ou étendre pour répondre à leurs besoins
• Flexibilité pour héberger sur différentes infrastructures, notamment le déploiement vers des services tels qu’Azure Static Web Apps.

Conditions préalables

• 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 de création d’une inscription d’application dans un locataire Microsoft Entra associé à votre abonnement Azure et autorisations pour accorder l’accès aux données dans votre centre d’API.

• Pour générer et déployer le portail, vous avez besoin d’un compte GitHub et des outils suivants installés sur votre ordinateur local :

  • Node.js et npm
  • Package Vite

Créer une inscription d’application Microsoft Entra

Commencez par configurer une inscription d'applications dans votre tenant Microsoft Entra ID. L’inscription de l’application permet au portail du Centre d’API d’accéder aux données de votre centre d’API pour le compte d’un utilisateur connecté.

Le Centre d’API peut configurer automatiquement l’inscription d’application, ou vous pouvez créer manuellement l’inscription de l’application.

Configurer automatiquement l’inscription de l’application

Pour configurer automatiquement l’inscription de l’application, procédez comme suit :

1. Dans le Portail Microsoft Azure, accédez à votre centre API.
2. Dans le menu de gauche, sélectionnezParamètres du > du Centre des API.
3. Sous l’onglet Fournisseur d’identité , sélectionnez Démarrer la configuration.
4. Sous l’onglet Installation rapide , sélectionnez Enregistrer + publier.

Si vous avez besoin d’accéder à l’inscription de l’application ultérieurement, vous pouvez la trouver dans le portail sous Inscriptions d’applications. L’application est nommée au format suivant : <api-center-name-apic-aad>.

Configurer manuellement l’inscription de l’application

Si vous souhaitez créer manuellement l’inscription de l’application, procédez comme suit :

1. Dans le portail Azure, accédez à Microsoft Entra ID>Manage>App Registrations.

2. Sélectionnez + Nouvelle inscription.

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

   1. Définissez Nom sur un nom significatif tel que api-center-portal
   2. Sous Types de compte pris en charge, sélectionnez Comptes dans cet annuaire organisationnel uniquement (<Nom de l’annuaire> – Locataire unique).
   3. Dans l’URI de redirection, sélectionnez Application monopage (SPA) et définissez l’URI. Entrez l’URI de votre déploiement du portail du Centre d’API, sous la forme suivante : https://<service-name>.portal.<location>.azure-apicenter.ms Remplacez <service name> et <location> par le nom de votre centre d'API et l'emplacement où il est déployé. Exemple : https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Sélectionnez Inscrire.

Configurer des URI de redirection supplémentaires pour l’extension VS Code

Lors de l’activation de l’affichage du portail du Centre d’API dans l’extension Visual Studio Code pour le Centre d’API, configurez également les URI de redirection suivants dans l’inscription de l’application :

1. Dans le portail Azure, accédez à votre inscription d’application.

2. Dans la page Gérer>l’authentification , sélectionnez Ajouter une plateforme , puis sélectionnez Applications mobiles et de bureau.

3. Configurez les trois URI de redirection personnalisés suivants :
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Remplacez <application-client-id> par l’ID d’application (client) de cette application. Vous trouverez cette valeur dans la page Vue d’ensemble de l’inscription de l’application.

Configurer l’environnement local

Suivez ces étapes pour générer et tester le portail du Centre d’API localement.

1. Clonez le dépôt API Center portal starter sur votre ordinateur local.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. Accédez au répertoire APICenter-Portal-Starter.

   cd APICenter-Portal-Starter
   

3. Basculez sur la branche principale.

   git checkout main
   

4. Pour configurer le service, copiez ou renommez le config.example.json fichier en config.json.

5. Modifiez ensuite le fichier pour qu’il config.json pointe vers votre service. Mettez à jour les valeurs dans le fichier comme suit :

   1. Remplacer <service name> et <region> par le nom de votre centre d’API et l’emplacement où il est déployé
   2. Remplacez <client ID> et <tenant ID> avec l’ID d’application (client) et l’ID d’annuaire (locataire) de l’inscription de l’application créée dans la section précédente.
   3. Mettez à jour la valeur de title avec un nom que vous souhaitez voir apparaître dans la barre supérieure du portail.

   {
     "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/Data.Read.All"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. Installez les packages requis.

   npm install
   

7. Démarrez le serveur de développement. La commande suivante démarre le portail en mode de développement s’exécutant localement :

   npm start
   

   Accédez au portail à l’adresse https://localhost:5173.

Déployer sur Azure

Pour connaître les étapes à suivre pour déployer le portail sur Azure Static Web Apps, consultez le référentiel de démarrage du portail du Centre d’API .

Activer la connexion au portail par les utilisateurs et groupes Microsoft Entra

Pour permettre à la connexion au portail du Centre des API d’accéder aux API, attribuez le rôle Lecteur de données du Centre d’API Azure aux utilisateurs ou groupes de votre organisation, limité à votre centre d’API.

Pour connaître les conditions préalables détaillées et les étapes à suivre pour attribuer un rôle aux utilisateurs et aux groupes, consultez Affecter des rôles Azure à l’aide du portail Azure. Les brèves étapes suivantes sont les suivantes :

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 :
   1. Dans la page Rôle , recherchez et sélectionnez Lecteur de données du Centre d’API Azure. Cliquez sur Suivant.
   2. Dans la page Membres, Dans Affecter l’accès, sélectionnez Utilisateur, groupe ou principal> de service+ Sélectionner des membres.
   3. Dans la page Sélectionner des membres , recherchez et sélectionnez les utilisateurs ou les groupes auxquels attribuer le rôle. Cliquez sur Sélectionner , puis sur Suivant.
   4. Vérifiez l'attribution du rôle, puis sélectionnez Vérifier + attribuer.

Après avoir configuré l’accès au portail, les utilisateurs configurés peuvent se connecter au portail et afficher les API dans votre centre d’API.

Résolution des problèmes

Erreur : « Vous n’êtes pas autorisé à accéder à ce portail »

Dans certaines conditions, un utilisateur peut rencontrer le message d’erreur suivant après la connexion au portail du Centre des API avec un compte d’utilisateur configuré :

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Tout d’abord, vérifiez que l’utilisateur reçoit le rôle Lecteur de données du Centre d’API Azure dans votre centre d’API.

Si l’utilisateur est affecté au rôle, il peut y avoir un problème avec l’inscription du fournisseur de ressources Microsoft.ApiCenter dans votre abonnement, et vous devrez peut-être réinscrire le fournisseur de ressources. Pour ce faire, exécutez la commande suivante dans Azure CLI :

az provider register --namespace Microsoft.ApiCenter

Impossible de se connecter au portail

Si les utilisateurs qui ont reçu le rôle Lecteur de données du Centre d’API Azure ne peuvent pas terminer le flux de connexion après avoir sélectionné Se connecter dans le portail du Centre d’API, il peut y avoir un problème avec la configuration du fournisseur d’identité Microsoft Entra ID.

Dans l’inscription de l’application Microsoft Entra, passez en revue et, si nécessaire, mettez à jour les paramètres d’URI de redirection pour vous assurer que l’URI correspond à l’URI du déploiement du portail du Centre d’API.

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

Si vous ne parvenez pas à demander des autorisations d’API au Centre d’API Azure dans votre inscription d’application Microsoft Entra pour le portail du Centre d’API, vérifiez que vous recherchez le Centre d’API Azure (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’inscription du fournisseur de ressources Microsoft.ApiCenter dans votre abonnement. Vous devrez peut-être réinscrire 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éinscrire le fournisseur de ressources, réessayez de demander des autorisations d’API.

Stratégie de support

Fournissez des commentaires, demandez des fonctionnalités et obtenez une prise en charge de l’implémentation de référence du portail du Centre d’API dans le référentiel de démarrage du portail du Centre d’API .

Contenu connexe

• Configurer le portail du Centre d’API
• Présentation du contrôle d’accès en fonction du rôle (RBAC) Azure
• Meilleures pratiques pour Azure RBAC
• Inscrire un fournisseur de ressources