Utiliser des principaux de service avec l’API Fabric pour GraphQL

Les principaux de service activent l’authentification par programmation non interactive auprès de l’API Fabric pour GraphQL. Contrairement aux principaux d’utilisateur qui exigent qu’une personne se connecte de manière interactive, les principaux de service utilisent les informations d’identification de l’application (ID client et secret) pour s’authentifier automatiquement. Cela les rend idéales pour les services principaux, les flux de travail automatisés, les pipelines CI/CD et toute application qui s’exécute sans interaction utilisateur.

Ce guide vous guide tout au long de la création d’une inscription d’application Microsoft Entra, de sa configuration en tant que principal de service et de son accès à vos API Fabric GraphQL. Vous allez apprendre à obtenir les informations d’identification nécessaires à l’authentification et à tester votre configuration avec un exemple de code.

Conseil / Astuce

Vous souhaitez voir les principaux de service en action ? Une fois cette configuration terminée, essayez le tutoriel Connecter des agents IA à l’API Fabric pour GraphQL avec un serveur MCP (Model Context Protocol) local. Il montre comment utiliser l’authentification du principal de service pour permettre aux agents IA comme GitHub Copilot d’interroger vos données Fabric à l’aide du langage naturel.

Qui utilise des principaux de service

L’authentification du service principal est conçue pour :

Ingénieurs de données qui créent des processus ETL automatisés et des opérations de données planifiées pour accéder aux entrepôts de données et aux lakehouses Fabric
Développeurs principaux créant des applications serveur à serveur qui consomment par programmation des données Fabric
Administrateurs de l’espace de travail Fabric configurant des services sans assistance et des processus en arrière-plan pour l’accès aux données
Ingénieurs DevOps implémentant des pipelines CI/CD qui interagissent avec des sources de données Fabric
Développeurs d’intégration qui créent des flux de travail automatisés qui nécessitent un accès aux données Fabric non interactif

Note

Pour les applications interactives utilisant des identités utilisateur (comme React ou des applications web), consultez plutôt Connecter des applications à l'API Fabric pour GraphQL. Ce guide se concentre sur l’authentification du service principal (non-interactive).

Prerequisites

Avant de configurer l’authentification du principal de service, vérifiez que vous disposez des points suivants :

Un espace de travail Microsoft Fabric avec des autorisations d’administrateur
API existante pour GraphQL dans votre espace de travail. Consultez Créer une API pour GraphQL dans Fabric et ajouter des données.
Autorisations de création d’inscriptions d’applications dans l’ID Microsoft Entra
Accès administrateur pour le locataire afin d'activer les paramètres du principal de service dans Fabric (ou demandez à votre administrateur de l'activer)

Étape 1 : Créer une inscription d’application Microsoft Entra

Suivez le guide complet sur Inscrivez une application Microsoft Entra et créez un principal de service pour créer l'enregistrement de l'application.

Points clés pour les principaux de service :

Ignorer les URI de redirection et les plateformes d’authentification (uniquement nécessaires pour les applications interactives)
Ignorer Autorisations et étendues d’API (les principaux de service n’utilisent pas d’autorisations déléguées)
Créez un secret client sous Certificats et secrets avec une période d’expiration appropriée

Important

Capturez ces trois valeurs lors de l’installation :

ID de locataire : trouvé dans l'ID Microsoft Entra sous vue d’ensemble>ID de locataire
ID client : trouvé dans votre inscription d'application dans la section Vue d'ensemble>ID d'application (client)
Clé secrète client : valeur secrète affichée lorsque vous créez une clé secrète client. Copiez immédiatement : elle n’est affichée qu’une seule fois.

Étape 2 : Activer les principaux de services dans les paramètres du tenant Fabric

Un administrateur de locataire Fabric doit activer l’utilisation du principal de service :

Dans le portail Fabric, accédez au portail d’administration>, puis aux paramètres du locataire
Sous Paramètres du développeur, activer les principes de service peuvent utiliser les API Fabric
Sélectionnez Appliquer

Ce paramètre rend votre inscription d’application visible dans Fabric pour l’attribution d’autorisations. Pour plus d’informations, consultez la gestion des identités.

Étape 3 : Accorder des autorisations dans Fabric

Votre principal de service a besoin de deux niveaux d’accès :

Option A : Autorisations d’API individuelles (recommandées pour la production)

Dans le portail Fabric, ouvrez l’espace de travail contenant votre API GraphQL
Sélectionnez les points de suspension (...) en regard de votre élément d’API
Sélectionner Gérer les autorisations
Sélectionner Ajouter un utilisateur
Rechercher et sélectionner le nom de l’inscription de votre application
Sélectionner Exécuter des requêtes et mutations (accorde l’autorisation d’exécution)
Sélectionner Accorder.

En outre, vérifiez que le principal de service dispose des autorisations de lecture/écriture appropriées sur la source de données sous-jacente (Lakehouse, Data Warehouse ou base de données SQL).

Option B : Rôle d’espace de travail (plus simple pour le développement/test)

Ajoutez votre inscription d'application comme membre de l'espace de travail avec le rôle Contributeur. Cela accorde l’accès à l’API GraphQL et à toutes les sources de données de l’espace de travail.

Dans le portail Fabric, ouvrez votre espace de travail
Sélectionner Gérer l’accès
Sélectionnez Ajouter des personnes ou des groupes
Rechercher le nom d’inscription de votre application
Sélectionner le rôle Contributeur
Sélectionnez Ajouter

Note

Vous n’attribuez pas de rôles Azure à votre inscription d’application dans Microsoft Entra ID pour ce scénario. Toutes les autorisations sont gérées dans Fabric via des autorisations d’API ou des rôles d’espace de travail.

Tester l’authentification de votre principal de service

Une fois configuré, testez votre principal de service en récupérant un jeton d’accès et en appelant votre API GraphQL.

Obtenir un jeton d’accès avec Node.js

Installez le package @azure/identity :

npm install @azure/identity

Créez un fichier pour récupérer votre jeton d’accès :

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

Enregistrez le fichier et exécutez-le :

node getToken.js

Cela récupère un jeton d’accès à partir de l’ID Microsoft Entra.

Appeler votre API GraphQL avec PowerShell

Utilisez le jeton pour interroger votre 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

Appeler votre API GraphQL avec cURL

Utilisez cURL pour interroger votre API :

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)>"}'

Terminer Node.js exemple (jeton + appel d’API)

Installez des dépendances :

npm install @azure/identity axios

Créez un exemple complet qui récupère un jeton et appelle votre API :

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();

Enregistrez et exécutez :

node callGraphQL.js

Résolution des problèmes

Inscription d’application non visible dans Fabric

Vérifiez que l'option Utilisation des API Fabric par les entités de service est activée dans les paramètres du client.
Patientez quelques minutes après l’activation du paramètre pour que les modifications se propagent

Erreurs d’authentification

Vérifiez que votre ID de locataire, votre ID client et votre clé secrète client sont corrects
Vérifiez que la clé secrète du client n’a pas expiré
Vérifiez que vous utilisez la portée https://api.fabric.microsoft.com/.default

Erreurs d’autorisation

Vérifiez que le principal de service dispose d’une autorisation d’exécution sur l’API GraphQL
Vérifier que le principal de service a un accès en lecture/écriture à la source de données sous-jacente
Vérifiez que le rôle dans l’espace de travail est Contributeur ou supérieur si vous utilisez des autorisations au niveau de celui-ci.

Créer une application Microsoft Entra dans Azure
Découvrez comment créer une API pour GraphQL dans Fabric et ajouter des données.
Découvrez comment interroger plusieurs sources de données dans l’API Fabric pour GraphQL.

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2026-01-21