Partager via

Auto-héberger votre portail Centre d’API

  • Article

Cet article présente le portail 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 dépôt de démarrage du portail Centre d’API.

Capture d’écran du portail du Centre des API après la connexion de l’utilisateur.

À propos du portail Centre d’API

Le portail Centre d’API est un site web que vous pouvez créer et héberger pour afficher l’inventaire des API de votre centre d’API. Le portail permet aux développeurs et à d’autres parties prenantes de votre organisation de découvrir les API et de voir leurs détails.

Vous pouvez créer et déployer une implémentation de référence du portail en utilisant le code du dépôt de démarrage du portail Centre d’API. Le portail utilise l’API de plan de données du Centre d’API Azure pour récupérer les données de votre centre d’API. L’accès utilisateur aux informations d’API est basé sur le contrôle d’accès en fonction du rôle Azure.

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

  • Un framework pour la publication et la gestion d’un portail d’API géré par le client avec GitHub Actions
  • Une plateforme de portail que les clients peuvent modifier ou étendre en fonction de leurs besoins
  • La flexibilité d’héberger sur différentes infrastructures, notamment le déploiement vers des services comme Azure Static Web Apps.

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.

  • 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 générer et déployer le portail, vous avez besoin d’un compte GitHub et des outils suivants installés sur votre machine locale :

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

Configurez d’abord une inscription d’application dans votre locataire Microsoft Entra ID. L'enregistrement de l'application permet au portail API Center d'accéder aux données de votre centre API au nom 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 Nom sur un nom significatif tel que api-center-portal

    • 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), puis définissez l’URI.

      • Pour les tests locaux, définissez l’URI sur https://localhost:5173.
      • Pour la production, définissez l’URI sur celui de votre déploiement de portail Centre d’API.

    • Sélectionnez Inscrire.

  4. Dans la page Vue d’ensemble, copiez l’ID d’application (client) et l’ID d’annuaire (locataire). Vous définissez ces valeurs quand vous générez le portail.

  5. Sur la page Autorisations API, sélectionnez + Ajouter une autorisation.

    1. Sur la page Demander des autorisations d'API, sélectionnez l'onglet API utilisées par mon organisation. Recherchez et sélectionnez Azure API Center. Vous pouvez également rechercher et sélectionner l'ID de l'application c3ca1a77-7a87-4dba-b8f8-eea115ae4573.
    2. Sur la page Demander des autorisations, sélectionnez uuser_impersonation.
    3. 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.

Configurer l’environnement local

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

  1. Clonez le dépôt de démarrage du portail Centre d’API sur votre machine locale.

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

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

    cd APICenter-Portal-Starter

  3. Consultez la branche main.

    git checkout main

  4. Pour configurer le service, copiez ou renommez le fichier public/config.example dans public/config.json.

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

    • Remplacez <service name> et <region> par le nom de votre centre d’API et la région où il est déployé
    • Remplacez <client ID> et <tenant ID> par l’ID d’application (client) et l’ID d’annuaire (locataire) de l’inscription d’application que vous avez créée dans la section précédente.
    • Mettez à jour la valeur de title avec le nom que vous voulez voir dans le portail.
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Installer les packages nécessaires.

    npm install

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

    npm start

    Accédez au portail sur https://localhost:5173.

Déployer sur Azure

Pour connaître les étapes de déploiement du portail sur Azure Static Web Apps, consultez le dépôt de démarrage du portail Centre d’API.

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

Les utilisateurs doivent se connecter pour voir les API de votre centre d’API. Pour activer la connexion, attribuez le rôle Azure API Center Data Reader aux utilisateurs ou aux groupes de votre organisation, limités à votre centre API.

Important

Par défaut, vous et les autres administrateurs du centre API n'avez pas accès aux API du portail API Center. 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.

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.

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

Remarque

Le premier utilisateur à se connecter au portail est invité à consentir aux autorisations demandées par l'enregistrement de l'application du portail API Center. Par la suite, les autres utilisateurs configurés ne sont pas invités à donner leur consentement.

Dépannage

Erreur : "Vous n'êtes pas autorisé à accéder à ce portail"

Dans certaines conditions, un utilisateur peut rencontrer le message d'erreur suivant après s'être connecté au portail API Center avec un compte utilisateur configuré :

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

Tout d’abord, confirmez que l’utilisateur dispose du rôle Azure API Center Data Reader dans votre centre API.

Si le rôle est attribué à l'utilisateur, il peut y avoir un problème avec l'enregistrement du fournisseur de ressources Microsoft.ApiCenter dans votre abonnement et 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

Impossible de se connecter au portail

Si les utilisateurs auxquels le rôle Azure API Center Data Reader a été attribué ne peuvent pas terminer le processus de connexion après avoir sélectionné Se connecter dans le portail API Center, il peut y avoir un problème avec la configuration du fournisseur d'identité Microsoft Entra ID.

Dans l’inscription d’application Microsoft Entra, vérifiez et mettez à jour si nécessaire les paramètres de l’URI de redirection pour qu’il corresponde à l’URI de déploiement du portail Centre d’API.

Impossible de sélectionner les autorisations Azure API Center dans l'inscription de l'application Microsoft Entra

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.

Politique de support

Fournissez des commentaires, demandez des fonctionnalités et bénéficiez de support pour l’implémentation de référence du portail Centre d’API dans le dépôt de démarrage du portail Centre d’API.

Contenu connexe