Partager via

Connecter les applications à l’API Fabric pour GraphQL

La connexion d’applications à l’API Fabric pour GraphQL permet à vos applications web, mobiles et back-end d’interroger des sources de données Fabric à l’aide d’une API moderne et efficace. Cette intégration nécessite une authentification appropriée via l’ID Microsoft Entra et la configuration de votre application pour appeler le point de terminaison GraphQL en toute sécurité.

Cet article vous guide tout au long de la connexion d’une application React à l’API Fabric GraphQL par :

  1. Création et configuration d’une application Microsoft Entra pour l’authentification
  2. Configuration d’un exemple d’API GraphQL dans Fabric avec des données à interroger
  3. Clonage et configuration d’une application React complète à partir de GitHub
  4. Test de la connexion authentifiée

Le tutoriel utilise React, mais les concepts d’authentification s’appliquent à n’importe quel langage. Pour obtenir des exemples en C#, Python ou d’autres langages, consultez le dépôt GitHub d’exemples Microsoft Fabric.

Qui doit connecter des applications

La configuration de la connexion d’application est essentielle pour :

  • Développeurs web et mobiles créant des applications consommant des données provenant de Fabric Lakehouses et d'entrepôts
  • Développeurs d’intégration connectant des données Fabric à des applications personnalisées et des workflows automatisés
  • Développeurs principaux créant des services qui s’intègrent à la plateforme d’analytique unifiée de Fabric
  • Ingénieurs données configurant des workflows de traitement des données automatisés qui consomment des données Fabric via des API

Utilisez ce guide lorsque vous devez authentifier et autoriser des applications à accéder à vos API Fabric GraphQL.

Prérequis

  • Outils de développement : vous avez besoin deNode.js (version LTS) et de Visual Studio Code installés sur votre ordinateur.

  • Avant de connecter une application, vérifiez que vous disposez d’une API pour GraphQL dans Fabric. Pour plus d’informations, consultez Créer une API pour GraphQL dans Fabric et ajouter des données.

  • L’API pour GraphQL nécessite que les applications utilisent Microsoft Entra pour l’authentification. Inscrivez et configurez votre application pour effectuer des appels d’API sur Fabric. Pour plus d’informations, consultez Créer une application Microsoft Entra dans Azure.

  • Les informations d’identification authentifiées (principal de l’utilisateur, principal de service ou identité managée) appelant l’API ont besoin d’autorisations d’exécution pour l’API GraphQL (Option Exécuter les requêtes et mutations lors de l’ajout d’autorisations d’accès direct). Si vous utilisez l’authentification unique (SSO) comme option de connectivité dans l’API, vérifiez que les informations d’identification disposent d’autorisations de lecture ou d’écriture dans la source de données choisie. Pour plus d’informations, consultez Se connecter à une source de données et construire votre schéma.

Résumé de l’authentification et des autorisations

L’accès à l’API GraphQL nécessite une authentification et une autorisation appropriées au niveau de l’API et au niveau de la source de données sous-jacente. Vous pouvez vous authentifier à l’aide d’un principal d’utilisateur (représentant un utilisateur individuel) ou d’un principal de service (représentant une application ou un service). Pour la connectivité à la source de données, vous pouvez utiliser l’authentification unique (SSO) où l’identité de l’appelant est transmise à la source de données ou aux informations d’identification enregistrées où une connexion préconfigurée est utilisée.

Le tableau suivant récapitule les différents scénarios d’authentification pris en charge et les autorisations minimales requises pour les clients accédant à l’API GraphQL :

Appelant de l’API Connectivité de la source de données Autorisations requises pour l’API GraphQL Autorisations requises pour la source de données Étendue de l’application Microsoft Entra
Nom d’utilisateur principal (UPN) Authentification unique (SSO) Exécuter des requêtes et des mutations au niveau de l’API Autorisations de lecture/écriture appropriées accordées à l’UPN au niveau de la source de données GraphQLApi.Execute.All
Principal de service (SPN) Authentification unique (SSO) Exécuter des requêtes et des mutations au niveau de l’API Autorisations de lecture/écriture appropriées accordées au SPN au niveau de la source de données Non applicable
Nom d’utilisateur principal (UPN) Informations d’identification enregistrées Exécuter des requêtes et des mutations au niveau de l’API Autorisations de lecture/écriture appropriées accordées aux informations d’identification enregistrées (connexion) au niveau de la source de données GraphQLApi.Execute.All
Principal de service (SPN) Informations d’identification enregistrées Exécuter des requêtes et des mutations au niveau de l’API Autorisations de lecture/écriture appropriées accordées au SPN au niveau de la source de données Non applicable

Créer une application Microsoft Entra

Avant que votre application puisse appeler l’API Fabric GraphQL, vous devez l’inscrire dans l’ID Microsoft Entra. Cette inscription crée une identité pour votre application et définit les autorisations dont elle a besoin. Le processus d’inscription génère un ID client (identificateur d’application) et établit le flux d’authentification utilisé par votre application pour obtenir des jetons d’accès.

Pour les applications React, vous configurez des paramètres d’application monopage (SPA) qui utilisent le flux PKCE , une méthode d’authentification sécurisée conçue pour les applications basées sur un navigateur où les secrets clients ne peuvent pas être stockés en toute sécurité.

  1. Inscrivez une application en suivant les étapes décrites dans Démarrage rapide : Inscrire une application avec la plateforme d’identités Microsoft.

  2. Les valeurs d’ID et d’ID d’annuaire (locataire) de l’application Microsoft Entra s’affichent dans la zone Résumé. Enregistrez ces valeurs, car vous en avez besoin lorsque vous configurez l’application React.

  3. Configurez les autorisations d’API pour que votre application puisse accéder à l’API Fabric GraphQL. Sous la liste Gérer, sélectionnez Autorisations d’API, puis Ajouter une autorisation.

  4. Ajoutez le service PowerBI, sélectionnez Autorisations déléguées, puis sélectionnez Autorisations GraphQLApi.Execute.All . Cette autorisation permet à votre application d’exécuter des requêtes et des mutations pour le compte de l’utilisateur connecté. Vérifiez que le consentement de l’administrateur n’est pas obligatoire.

  5. Revenez à la liste Gérer, sélectionnez Authentification>Ajouter une> de plateforme.

  6. À des fins de développement local, ajoutez http://localhost:3000 sous URI de redirection, puis vérifiez que l’application est activée pour le flux de code d’autorisation avec la clé de preuve PKCE (Proof Key for Code Exchange). Sélectionnez le bouton Configurer pour enregistrer vos modifications. Si l’application rencontre une erreur liée aux requêtes inter-origines, ajoutez la plateforme Des applications mobiles et de bureau à l’étape précédente avec le même URI de redirection.

  7. Revenez à Authentification, faites défiler jusqu’à Paramètres avancés et, sous Autoriser les flux clients publics, sélectionnez Oui pour Activer les flux suivants pour mobile et bureau.

Configurer un exemple d’API GraphQL pour l’accès aux applications

Avec votre application Microsoft Entra inscrite, vous avez besoin d’une API GraphQL dans Fabric pour interroger. Cette section vous guide tout au long de la création d’un exemple d’API à l’aide du jeu de données des jours fériés de Fabric. Cela vous donne une API de travail pour tester l’authentification et la récupération des données sans avoir à configurer vos propres sources de données.

L’exemple d’API expose les données de congés d’une table Lakehouse, que votre application React interroge pour afficher les jours fériés.

  1. Dans la page d’accueil du portail Fabric, sélectionnez Engineering données dans la liste des charges de travail.

  2. Dans l’expérience d’ingénierie des données, sélectionnez Utiliser un exemple, puis, sous Lakehouse, sélectionnez Jours fériés pour créer automatiquement un Lakehouse avec des données de jours fériés.

    Capture d’écran de la sélection de l’exemple d’option Data Lakehouse.

  3. Suivez les étapes de créer une API pour GraphQL pour créer une API GraphQL et sélectionnez lakehouse que vous avez créée. Ajoutez la table des jours fériés afin que les clients puissent accéder à ces données.

    Capture d’écran de l’ajout de l’exemple Lakehouse en tant que source de données GraphQL.

  4. Avant de générer l’application React, vérifiez que votre API fonctionne correctement en la testant dans l’éditeur d’API. Utilisez la requête suivante : il s’agit de la même requête que votre application React s’exécute ultérieurement :

     query {
 publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
     items {
       countryOrRegion
       holidayName
       date
     }
   }
 }

  5. Sélectionnez Copier le point de terminaison dans la barre d’outils de l’élément d’API.

    Capture d’écran des options de barre d’outils d’un élément d’API.

  6. Dans l'écran Copier le lien, sélectionnez Copier.

    Capture d’écran de la boîte de dialogue Copier le lien, montrant où sélectionner Copier.

  7. Enregistrez l’ID client et l’ID de locataire à partir de l’application Microsoft Entra et de l’URI du point de terminaison. Vous avez besoin de ces valeurs lorsque vous configurez l’application React.

Cloner et configurer l’application React

Maintenant que vous avez configuré l’application Microsoft Entra et l’API GraphQL, vous pouvez configurer une application React pour les connecter. L'application utilise la bibliothèque d'authentification Microsoft (MSAL) pour gérer l'authentification et effectue des requêtes GraphQL avec des jetons Bearer.

  1. Clonez le référentiel d’exemples à partir de GitHub :

    git clone https://github.com/microsoft/fabric-samples.git

  2. Accédez au dossier de l’application React :

    cd fabric-samples/docs-samples/data-engineering/GraphQL/React

    Le dossier contient une application React complète. Vous devez uniquement modifier src/authConfig.js pour configurer votre point de terminaison et vos informations d’identification spécifiques.

  3. Ouvrez le projet dans votre éditeur de code :

    code .

  4. Dans votre éditeur, accédez au src dossier et ouvrez authConfig.js.

  5. Remplacez les valeurs de remplacement suivantes par vos informations spécifiques :

    Important

    Dans le même fichier, la loginRequest constante inclut l’étendue https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Cette étendue exacte est requise pour accéder aux API Fabric GraphQL. Ne supprimez pas ou ne modifiez pas cette étendue ; sinon, l’authentification échoue.

  6. Enregistrez le fichier.

  7. Dans votre terminal, accédez au dossier racine du projet et exécutez :

    npm install

    Cela installe toutes les dépendances requises.

Tester l’application

Une fois l’application configurée, exécutez-la localement pour vérifier que tout fonctionne correctement :

  1. Dans votre terminal, exécutez :

    npm start

    Cette commande démarre le serveur de développement et ouvre l’application dans votre navigateur.

  2. Terminez le flux d’authentification lorsque l’application se charge à http://localhost:3000. Suivez les étapes de connexion décrites dans la section didacticiel Appeler l’API à partir de l’application.

  3. Après vous être connecté avec succès, choisissez le bouton API de requête Fabric pour les données GraphQL. Cela déclenche le flux d’authentification, acquiert un jeton d’accès et exécute la requête GraphQL sur votre API Fabric.

    Capture d’écran de l’exemple d’application React après la connexion.

  4. Si tout est configuré correctement, l’application affiche les jours fériés dans une table. Cela confirme que :

    • Votre application Microsoft Entra dispose des autorisations appropriées
    • Le jeton d’accès a été acquis avec succès
    • L’API GraphQL a authentifié la requête
    • Requête exécutée sur les données Lakehouse

    Capture d’écran de l’exemple d’application React après avoir reçu la requête GraphQL.

Autres commandes npm

Au-delà npm start et npm install, vous pouvez utiliser ces commandes npm courantes pour différents scénarios de développement :

  • npm run dev - Autre moyen de démarrer le serveur de développement
  • npm run build - Créer une build de production optimisée de votre application
  • npm run preview - Tester la build de production localement avant le déploiement
  • npm test - Exécuter des tests automatisés pour vérifier que votre code fonctionne correctement

Contenu connexe

Maintenant que vous disposez d’une application opérationnelle connectée à votre API Fabric GraphQL, explorez ces ressources pour créer des solutions plus sophistiquées :

  • Last updated on