Connecter les applications à l’API Fabric pour GraphQL

Article
10/25/2024

Remarque

L’API Microsoft Fabric pour GraphQL est en aperçu.

Pour connecter une application à une API pour GraphQL, vous avez besoin de trois informations importantes : un ID client, votre ID de locataire et votre adresse de point de terminaison GraphQL dans Fabric. Dans les sections suivantes, nous présentons comment créer et récupérer tous les détails dont vous avez besoin et comment accéder à votre API à l’aide d’un exemple d’application.

Prérequis

Actuellement, l’API pour GraphQL nécessite que les applications utilisent Microsoft Entra pour l’authentification. Votre application doit être inscrite et configurée de manière appropriée pour effectuer des appels d’API à partir de Fabric. Pour plus d’informations, consultez Créer une application Microsoft Entra dans Azure.
L’utilisateur authentifié appelant l’API doit être membre de l’espace de travail où se trouvent à la fois l’API et les éléments de source de données avec un rôle Collaborateur. Pour plus d’informations, consultez Accorder aux utilisateurs l’accès aux espaces de travail.
Avant de connecter une application, vous devez disposer 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.

Créer une application Microsoft Entra

Dans les étapes suivantes, nous présentons comment configurer la prise en charge d’une application ReactJS dans Microsoft Entra.

Connectez-vous au portail Azure.
Recherchez et sélectionnez Microsoft Entra ID.
Dans la liste Gérer, cliquez sur Enregistrement d’applications.
Sélectionnez Nouvelle inscription.
Entrez les informations obligatoires :
- Nom : entrez un nom pour votre application.
- Types de compte pris en charge : sélectionnez les comptes à prendre en charge par l’application.
- (facultatif) URI de redirection : entrez un URI si nécessaire. GraphQL.Execute.All ou Item.Execute.All
Sélectionnez Inscrire. Les valeurs ID d’application (locataire) et ID d’annuaire (locataire) de votre application Microsoft Entra s’affichent dans la zone Résumé. Enregistrez ces valeurs au fur et à mesure qu’elles sont requises ultérieurement.
Dans la liste Gérer, sélectionnez Autorisations d’API, puis Ajouter une autorisation.
Ajoutez le service PowerBI, sélectionnez Autorisations déléguées, puis sélectionnez , et Datamart.ReadWrite.All autorisations. Vérifiez que le consentement administrateur n’est pas obligatoire.
Revenez à la liste Gérer et sélectionnez Authentification, Ajouter une plateforme, puis Application monopage.
À des fins de développement local, ajoutez http://localhost:3000 sous Redirection des URI et assurez-vous que l’application est activée pour le flux de code d’autorisation avec la clé de preuve pour l’échange de code (PKCE). Sélectionnez le bouton Configurer pour enregistrer vos modifications. Si l’application reçoit une erreur liée aux demandes inter-origines, ajoutez la plateforme Applications de bureau et mobiles de l’étape précédente avec le même URI de redirection.
Revenez à Autorisation, faites défiler vers le bas jusqu’à Paramètres avancés et, sous Autoriser les flux de clients publics, sélectionnez Oui pour Activer les flux mobiles et de bureau suivants.

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

Dans cet exemple, nous créons une API GraphQL pour exposer des exemples de données Lakehouse aux clients.

Dans la page d’accueil du portail Fabric, sélectionnez Ingénieurs Données ing dans la liste des charges de travail.
Dans l’expérience Ingénieurs Données, sélectionnez Utiliser un exemple et, sous Lakehouse, sélectionnez Jours fériés pour créer automatiquement un Lakehouse avec des données de jours fériés.
En suivant les étapes de la section Créer une API pour GraphQL, créez une API GraphQL et sélectionnez le Lakehouse que vous avez créé. Ajoutez la table des jours fériés pour permettre aux clients d’accéder à ces données.

Testez l’API GraphQL dans l’éditeur d’API à l’aide de l’exemple de requête suivant. Il s’agit de la même requête que celle que nous utilisons dans notre application cliente React :

 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
     }
   }
 }

Sélectionnez Copier le point de terminaison dans la barre d’outils de l’élément d’API.
Dans l'écran Copier le lien, sélectionnez Copier.
En tant qu’ID client et ID de locataire de l’application Microsoft Entra enregistrée précédemment, copiez l’URI du point de terminaison, car il est nécessaire ultérieurement.

Configurer une application React pour accéder à l’API jours fériés

Nous utilisons une application React existante comme point de départ. Suivez toutes les étapes du didacticiel Créer une application à page unique React et préparez-la à l’authentification pour créer un projet React avec l’authentification Microsoft Entra déjà configurée, y compris des fichiers et dossiers supplémentaires requis pour être ajoutés à la structure du projet. Nous devons uniquement modifier trois fichiers pour adapter l’application à notre cas d’usage GraphQL.

Dans le dossier src, ouvrez le fichier authConfig.js et remplacez son contenu par l’extrait de code suivant :

 /*
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */

 import { LogLevel } from "@azure/msal-browser";

 /**
  * Configuration object to be passed to MSAL instance on creation. 
  * For a full list of MSAL.js configuration parameters, visit:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
  */

 export const graphqlConfig = {
     graphqlEndpoint: "`Enter_the_GraphQL_Endpoint_Here"
 };

 export const msalConfig = {
     auth: {
         clientId: "Enter_the_Application_Id_Here",
         authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
         redirectUri: "http://localhost:3000",
     },
     cache: {
         cacheLocation: "sessionStorage", // This configures where your cache will be stored
         storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
     },
     system: {	
         loggerOptions: {	
             loggerCallback: (level, message, containsPii) => {	
                 if (containsPii) {		
                     return;		
                 }		
                 switch (level) {
                     case LogLevel.Error:
                         console.error(message);
                         return;
                     case LogLevel.Info:
                         console.info(message);
                         return;
                     case LogLevel.Verbose:
                         console.debug(message);
                         return;
                     case LogLevel.Warning:
                         console.warn(message);
                         return;
                     default:
                         return;
                 }	
             }	
         }	
     }
 };

 /**
  * Scopes you add here will be prompted for user consent during sign-in. 
  * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
  * For more information about OIDC scopes, visit: 
  * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
  */
 export const loginRequest = {
     scopes: ["https://analysis.windows.net/powerbi/api/Item.Execute.All","https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All"]
 };

 /**
  * Add here the scopes to request when obtaining an access token for MS Graph API. For more information, see:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
  */
 export const graphConfig = {
     graphMeEndpoint: "https://graph.microsoft.com/v1.0/me",
 };

Comme vous pouvez le voir dans le code ci-dessus, il est important d’utiliser l’étendue correcte pour accéder à l’application. Dans notre cas, https://analysis.windows.net/powerbi/api/Item.Execute.All et https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All.

Important

Les étendues sont susceptibles de changer pendant la préversion de l’API Microsoft Fabric pour GraphQL.

Remplacez les valeurs suivantes par les valeurs du centre d’administration Microsoft Entra.
- clientId – Identificateur de l’application, également appelé client. Remplacez Enter_the_Application_Id_Here par la valeur d’ID d’application (client) enregistrée précédemment à partir de la page vue d’ensemble de l’application Microsoft Entra inscrite.
- authority – Il se compose de deux parties :
  - L’instance est le point de terminaison du fournisseur de cloud. Vérifiez les différents points de terminaison disponibles dans les clouds nationaux.
  - L’ID du locataire est l’identificateur du locataire dans lequel l’application est inscrite. Remplacez Enter_the_Tenant_Info_Here par la valeur de l’ID du répertoire (tenant) enregistrée précédemment dans la page de présentation de l’application inscrite.
- graphQLEndpoint : l’API Fabric pour le point de terminaison GraphQL. Remplacez Enter_the_GraphQL_Endpoint_Here par le point de terminaison de l’API GraphQL enregistré précédemment.
Enregistrez le fichier.

Dans le même dossier src, ouvrez le fichier App.jsx et remplacez son contenu par l’extrait de code suivant :

 import React, { useState } from 'react';
 import { PageLayout } from './components/PageLayout';
 import { loginRequest, graphqlConfig } from './authConfig';
 import { ProfileData } from './components/ProfileData';
 import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal } from '@azure/msal-react';
 import './App.css';
 import Button from 'react-bootstrap/Button';
 import Spinner from 'react-bootstrap/Spinner';

 /**
 * Renders information about the signed-in user or a button to retrieve data about the user
 */
 const ProfileContent = () => {
   const { instance, accounts } = useMsal();
   const [graphqlData, setGraphqlData] = useState(null);
   const [display, setDisplay] = useState(false);

   function RequestGraphQL() {
       // Silently acquires an access token which is then attached to a request for GraphQL data
       instance
           .acquireTokenSilent({
               ...loginRequest,
               account: accounts[0],
           })
           .then((response) => {
               callGraphQL(response.accessToken).then((response) => setGraphqlData(response));
           });
   }

 async function callGraphQL(accessToken) {
   setDisplay(true);
   const query = `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
       }
     }
   }`;
   fetch(graphqlConfig.graphqlEndpoint, {
           method: 'POST',
           headers: {
               'Content-Type': 'application/json',
               'Authorization': `Bearer ${accessToken}`,
           },
           body: JSON.stringify({ 
               query: query
           })
       })
       .then((res) => res.json())
       .then((result) => setGraphqlData(result));
 }

   return (
       <>
           <h5 className="card-title">Welcome {accounts[0].name}</h5>
           <br/>
           {graphqlData ? (
               <ProfileData graphqlData={graphqlData} />
           ) : (
               <Button variant="primary" onClick={RequestGraphQL}>
                   Query Fabric API for GraphQL Data 
                   {display ? (
                         <Spinner
                             as="span"
                             animation="border"
                             size="sm"
                             role="status"
                             aria-hidden="true"
                         />
                     ) : null}
               </Button>
           )}
       </>
   );
 };

 /**
 * If a user is authenticated the ProfileContent component above is rendered. Otherwise a message indicating a user is not authenticated is rendered.
 */
 const MainContent = () => {
   return (
       <div className="App">
           <AuthenticatedTemplate>
               <ProfileContent />
           </AuthenticatedTemplate>

           <UnauthenticatedTemplate>
               <h5>
                   <center>
                       Please sign-in to see your profile information.
                   </center>
               </h5>
           </UnauthenticatedTemplate>
       </div>
   );
 };

 export default function App() {
   return (
       <PageLayout>
           <center>
               <MainContent />
           </center>
       </PageLayout>
   );
 }

Enregistrez le fichier.

Enfin, sous le dossier src/components, ouvrez le fichier ProfileData.jsx et remplacez son contenu par l’extrait de code suivant :

 import React from "react";
 import ListGroup from 'react-bootstrap/ListGroup'; 
 import Table from 'react-bootstrap/Table';
 /**
  * Renders information about the user obtained from MS Graph 
  * @param props
  */
 export const ProfileData = (props) => {
   const holidays = props.graphqlData.data.publicholidays.items;
   return (
     <Table striped bordered hover responsive>
     <thead>
       <tr>
         <th>Country</th>
         <th>Holiday</th>
         <th>Date</th>
       </tr>
     </thead>
     <tbody>
       {holidays.map((item,i) => (
       <tr key={i}>
         <td>{item.countryOrRegion}</td>
         <td>{item.holidayName}</td>
         <td>{item.date}</td>
       </tr>
       ))}
       </tbody>
     </Table>
 )};

Enregistrez toutes les modifications du fichier.
Dans l’application de terminal de votre choix, accédez au dossier racine du projet React et exécutez la commande npm start pour tester l’application localement.
Une fois l’application chargée dans votre navigateur à partir de http://localhost:3000, suivez les étapes dans la dernière partie du tutoriel Appeler l’API à partir de l’application pour l’authentification.
Une fois connecté, cliquez sur le bouton API de requête Fabric pour les données GraphQL.
Une demande authentifiée réussie auprès de l’API GraphQL dans Fabric renvoie les données de la requête GraphQL au Lakehouse dans notre application cliente React :

Utiliser un principal de service

Bien que les étapes décrites dans la section précédente soient requises pour fournir l’accès aux principaux d’utilisateur, il est également possible d’accéder à l’API GraphQL avec un principal de service :

Suivez les étapes décrites dans la section précédente pour créer une deuxième application Microsoft Entra. Dans la nouvelle application, ajoutez une clé secrète client sous Certificats et secrets, pour plus d’informations, consultez Inscrire une application Microsoft Entra et créer un principal de service.
Dans le portail d’administration du locataire, accédez aux paramètres du locataire. Sous Paramètres du développeur, activez les principaux de service peuvent utiliser les API Fabric. Avec ce paramètre activé, l’application est visible dans le portail Fabric pour l’attribution de rôle ou d’autorisations. Vous trouverez plus d’informations sur la prise en charge des identités.
Le principal de service doit accéder à l’API GraphQL et à la source de données. Dans le portail Fabric, ajoutez l’application en tant que membre de l’espace de travail avec un rôle contributeur où se trouvent à la fois l’API GraphQL et les éléments de source de données.

Étant donné qu’un principal de service nécessite un certificat ou une clé secrète client, il n’est pas pris en charge par la bibliothèque d’authentification Microsoft (MSAL) dans les applications monopage (SPA), comme l’application React que nous avons créée à la dernière étape. Vous pouvez tirer parti d’un service principal correctement sécurisé avec une logique d’autorisation bien définie en fonction de vos besoins et cas d’utilisation.

Une fois que votre API est configurée pour être accessible par un principal de service, vous pouvez la tester localement à l’aide d’une application simple Node.JS dans votre ordinateur local :

const { ClientSecretCredential } = require('@azure/identity');

// Define your Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

const scope = "https://api.fabric.microsoft.com/.default"; // The scope of the token to access Fabric

// Create a credential object with service principal details
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Function to retrieve the token
async function getToken() {
    try {
        // Get the token for the specified scope
        const tokenResponse = await credential.getToken(scope);
        console.log("Access Token:", tokenResponse.token);
    } catch (err) {
        console.error("Error retrieving token:", err.message);
    }
}

Après avoir installé les dépendances (@azure/identity) avec votre gestionnaire de package de Node.JS choix, modifiez le fichier avec les informations requises, enregistrez et exécutez-le (node <filename.js>), vous pourrez récupérer un jeton à partir de Microsoft Entra.

Le jeton peut ensuite être utilisé pour appeler votre API GraphQL à l’aide de PowerShell en remplaçant les détails appropriés par le jeton que vous venez de récupérer, la requête GraphQL que vous souhaitez exécuter et le point de terminaison de l’API GraphQL :

$headers = @{
    Authorization = "Bearer <YOUR_TOKEN>"
    'Content-Type' = 'application/json'
}

$body = @{
    query = @"
    <YOUR_GRAPHQL_QUERY>
"@
}

# Make the POST request to the GraphQL API
$response = Invoke-RestMethod -Uri "<YOUR_GRAPHQL_API_ENDPOINT>" -Method POST -Headers $headers -Body ($body | ConvertTo-Json)

# Output the response
$response | ConvertTo-Json -Depth 10

Vous pouvez également utiliser cURL pour obtenir le même résultat :

curl -X POST <YOUR_GRAPHQL_API_ENDPOINT> \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"query": "<YOUR_GRAPHQL_QUERY(in a single line)>"}'

À des fins de test local, le code Node.JS peut être légèrement modifié avec une dépendance supplémentaire (axios) pour récupérer le jeton et appeler l’API dans une seule exécution :

const { ClientSecretCredential } = require('@azure/identity');
const axios = require('axios');

// Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

// GraphQL API details
const graphqlApiUrl = "YOUR_GRAPHQL_API_ENDPOINT>";
const scope = "https://api.fabric.microsoft.com/.default"; // The scope to request the token for

// The GraphQL query
const graphqlQuery = {
  query: `
  <YOUR_GRAPHQL_QUERY>
  `
};

// Function to retrieve a token and call the GraphQL API
async function fetchGraphQLData() {
  try {
    // Step 1: Retrieve token using the ClientSecretCredential
    const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    const tokenResponse = await credential.getToken(scope);
    const accessToken = tokenResponse.token;

    console.log("Access token retrieved!");

    // Step 2: Use the token to make a POST request to the GraphQL API
    const response = await axios.post(
      graphqlApiUrl,
      graphqlQuery,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Step 3: Output the GraphQL response data
    console.log("GraphQL API response:", JSON.stringify(response.data));
    
  } catch (err) {
    console.error("Error:", err.message);
  }
}

// Execute the function
fetchGraphQLData();

Autres langages

Recherchez des exemples C#, Python et d’autres langages pour vous connecter à votre API GraphQL dans le dépôt GitHub d’exemples Microsoft Fabric.

Partager via

Connecter les applications à l’API Fabric pour GraphQL

Prérequis

Créer une application Microsoft Entra

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

Configurer une application React pour accéder à l’API jours fériés

Utiliser un principal de service

Autres langages

Commentaires

Ressources supplémentaires

Partager via

Connecter les applications à l’API Fabric pour GraphQL

Prérequis

Créer une application Microsoft Entra

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

Configurer une application React pour accéder à l’API jours fériés

Utiliser un principal de service

Autres langages

Contenu connexe

Commentaires

Ressources supplémentaires