Teilen über

Verwenden von Dienstprinzipalen mit Fabric-API für GraphQL

Dienstprinzipale ermöglichen die nicht interaktive, programmgesteuerte Authentifizierung für die Fabric-API für GraphQL. Im Gegensatz zu Benutzerprinzipalen, die eine interaktive Anmeldung erfordern, verwenden Dienstprinzipale Anwendungsanmeldeinformationen (Client-ID und geheimer Schlüssel), um sich automatisch zu authentifizieren. Dies macht sie ideal für Back-End-Dienste, automatisierte Workflows, CI/CD-Pipelines und jede Anwendung, die ohne Benutzerinteraktion ausgeführt wird.

Dieser Leitfaden führt Sie durch die Registrierung einer Microsoft Entra-App, die Konfiguration als Dienstprinzipal und das Gewähren des Zugriffs auf Ihre GraphQL-APIs von Fabric. Sie erfahren, wie Sie die für die Authentifizierung erforderlichen Anmeldeinformationen abrufen und Ihr Setup mit Beispielcode testen.

Tipp

Möchten Sie Dienstprinzipale in Aktion sehen? Nachdem Sie diese Einrichtung abgeschlossen haben, probieren Sie das Lernprogramm "KI-Agents mit Fabric-API für GraphQL mit einem lokalen MCP-Server (Model Context Protocol)" aus. Es veranschaulicht, wie Sie die Dienstprinzipal-Authentifizierung verwenden, um einem KI-Agent wie GitHub Copilot zu ermöglichen, mithilfe natürlicher Sprache Abfragen an Ihre Fabric-Daten zu stellen.

Wer Dienstprinzipale verwendet

Die Dienstprinzipalauthentifizierung wurde zu folgendem Zweck entwickelt:

  • Data Engineers, die automatisierte ETL-Prozesse und geplante Datenoperationen entwickeln, die auf Fabric-Lakehouses und -Warehouses zugreifen.
  • Back-End-Entwickler erstellen Server-zu-Server-Anwendungen, die Fabric-Daten programmgesteuert nutzen
  • Fabric-Arbeitsbereichsadministratoren einrichten unbeaufsichtigte Dienste und Hintergrundprozesse für den Datenzugriff
  • DevOps-Techniker implementieren CI/CD-Pipelines, die mit Fabric-Datenquellen interagieren
  • Integrationsentwickler erstellen automatisierte Workflows, für die kein interaktiver Fabric-Datenzugriff erforderlich ist

Hinweis

Interaktive Anwendungen, die Benutzerprinzipale verwenden (z. B. React oder Web-Apps), finden Sie stattdessen unter Verbinden von Anwendungen mit der Fabric-API für GraphQL . Dieser Leitfaden konzentriert sich auf die Dienstprinzipalauthentifizierung (nicht interaktiv).

Voraussetzungen

Stellen Sie sicher, dass Sie vor dem Einrichten der Dienstprinzipalauthentifizierung Folgendes haben:

  • Ein Microsoft Fabric-Arbeitsbereich mit Administratorberechtigungen
  • Eine vorhandene API für GraphQL in Ihrem Arbeitsbereich. Siehe Erstellen einer API für GraphQL in Fabric und Hinzufügen von Daten.
  • Berechtigungen zum Erstellen von App-Registrierungen in der Microsoft Entra-ID
  • Mandantenadministratorzugriff erforderlich, um Dienstprinzipaleinstellungen in Fabric zu aktivieren (oder bitten Sie Ihren Administrator, dies zu tun).

Schritt 1: Erstellen einer Microsoft Entra-App-Registrierung

Befolgen Sie den vollständigen Leitfaden unter Registrieren einer Microsoft Entra-App und Erstellen eines Dienstprincipals um Ihre App-Registrierung zu erstellen.

Wichtige Punkte für Serviceprinzipien:

  • Umleitungs-URIs und Authentifizierungsplattformen überspringen (nur für interaktive Apps erforderlich)
  • Überspringen API-Berechtigungen und -Bereiche (Dienstprinzipale verwenden keine delegierten Berechtigungen)
  • Erstellen Sie einen geheimen Clientschlüssel unter Zertifikaten und geheimen Schlüsseln mit einem geeigneten Ablaufzeitraum.

Von Bedeutung

Erfassen Sie diese drei Werte während des Setups:

  • Mandanten-ID: In Microsoft Entra ID unter Übersicht>Mandanten-ID gefunden
  • Client-ID: In Ihrer App-Registrierung unterÜbersichtsanwendungs-ID> (Client)-ID gefunden
  • Geheimer Clientschlüssel: Der geheime Wert, der beim Erstellen eines neuen geheimen Clientschlüssels angezeigt wird. Kopieren Sie sofort – sie wird nur einmal angezeigt.

Schritt 2: Aktivieren von Diensteprinzipalen in den Fabric-Mandanteneinstellungen

Ein Fabric-Mandantenadministrator muss die Dienstprinzipalverwendung aktivieren:

  1. Wechseln Sie im Fabric-Portal zu denMandanteneinstellungen des >.
  2. Unter Entwicklereinstellungen aktivieren Sie, dass Dienstprinzipale Fabric-APIs verwenden können.
  3. Wählen Sie Übernehmen aus.

Diese Einstellung macht ihre App-Registrierung in Fabric für die Berechtigungszuweisung sichtbar. Weitere Informationen finden Sie unter Identitätsunterstützung.

Schritt 3: Erteilen von Berechtigungen in Fabric

Ihr Dienstprinzipal benötigt zwei Zugriffsebenen:

  1. Öffnen Sie im Fabric-Portal den Arbeitsbereich, der Ihre GraphQL-API enthält.
  2. Wählen Sie die Auslassungspunkte (...) neben Ihrem API-Element aus.
  3. Wählen Sie "Berechtigungen verwalten" aus.
  4. Wählen Sie "Benutzer hinzufügen" aus.
  5. Suchen und Auswählen des App-Registrierungsnamens
  6. Select Run Queries and Mutations (gewährt die Berechtigung 'Ausführen')
  7. Klicken Sie auf Gewähren.

Stellen Sie außerdem sicher, dass der Dienstprinzipal über entsprechende Lese-/Schreibberechtigungen für die zugrunde liegende Datenquelle verfügt (Lakehouse, Data Warehouse oder SQL-Datenbank).

Option B: Rolle im Arbeitsbereich (einfacher für Entwicklung und Tests)

Fügen Sie Ihre App-Registrierung als Arbeitsbereichsmitglied mit der Rolle "Mitwirkender" hinzu. Dadurch erhalten Sie Zugriff auf die GraphQL-API und alle Datenquellen im Arbeitsbereich.

  1. Öffnen Sie im Fabric-Portal Ihren Arbeitsbereich.
  2. Wählen Sie Zugriff verwalten aus
  3. Wählen Sie "Personen oder Gruppen hinzufügen" aus.
  4. Suchen nach ihrem App-Registrierungsnamen
  5. Auswählen der Rolle "Mitwirkender"
  6. Wählen Sie Hinzufügen aus.

Screenshot der GraphQL-API-Berechtigungen.

Hinweis

Sie weisen Ihrer App-Registrierung in Microsoft Entra-ID für dieses Szenario keine Azure-Rollen zu. Alle Berechtigungen werden in Fabric über API-Berechtigungen oder Arbeitsbereichsrollen verwaltet.

Testen Sie die Dienstprinzipal-Authentifizierung

Nachdem der Dienstprinzipal konfiguriert wurde, testen Sie ihn, indem Sie ein Zugriffstoken abrufen und Ihre GraphQL-API aufrufen.

Abrufen eines Zugriffstokens mit Node.js

Installieren Sie das Paket @azure/identity:

npm install @azure/identity

Erstellen Sie eine Datei zum Abrufen Ihres Zugriffstokens:

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

Speichern Sie die Datei, und führen Sie sie aus:

node getToken.js

Dadurch wird ein Zugriffstoken von der Microsoft Entra-ID abgerufen.

Aufrufen der GraphQL-API mit PowerShell

Verwenden Sie das Token, um Ihre GraphQL-API abzufragen:

$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

Aufrufen der GraphQL-API mit cURL

Verwenden Sie cURL, um Ihre API abzufragen:

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

Vollständiges Node.js Beispiel (Token + API-Aufruf)

Installieren von Abhängigkeiten:

npm install @azure/identity axios

Erstellen Sie ein vollständiges Beispiel, das ein Token abruft und Ihre API aufruft:

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

Speichern und ausführen:

node callGraphQL.js

Problembehandlung

App-Registrierung in Fabric nicht sichtbar

  • Überprüfen Sie, ob in den Mandanteneinstellungen die Option aktiviert ist, dass Dienstprinzipale Fabric-APIs verwenden können.
  • Warten Sie einige Minuten, nachdem sie die Einstellung aktiviert hat, damit Änderungen weitergegeben werden.

Authentifizierungsfehler

  • Bestätigen Sie, dass Ihre Mandanten-ID, Client-ID und Client-Geheimnis korrekt sind.
  • Überprüfen, ob der geheime Clientschlüssel nicht abgelaufen ist
  • Stellen Sie sicher, dass Sie den Umfang verwenden https://api.fabric.microsoft.com/.default

Berechtigungsfehler

  • Überprüfen Sie, ob der Dienstprinzipal über die Berechtigung "Execute" für die GraphQL-API verfügt.
  • Überprüfen, ob der Dienstprinzipal Lese-/Schreibzugriff auf die zugrunde liegende Datenquelle hat
  • Bitte bestätigen Sie, dass die Rolle im Arbeitsbereich "Mitwirkender" oder höher ist, falls Berechtigungen auf Arbeitsbereichsebene genutzt werden.

Verwandte Inhalte

  • Last updated on