Teilen über

Verbinden von Anwendungen mit der Fabric-API für GraphQL

Durch das Verbinden von Anwendungen mit der Fabric-API für GraphQL können Web-, Mobile- und Back-End-Anwendungen Fabric-Datenquellen mithilfe einer modernen, effizienten API abfragen. Diese Integration erfordert eine ordnungsgemäße Authentifizierung über die Microsoft Entra-ID und die Konfiguration Ihrer Anwendung, um den GraphQL-Endpunkt sicher aufzurufen.

Dieser Artikel zeigt Ihnen, wie Sie eine React-Anwendung mit der Fabric GraphQL-API verbinden, einschließlich:

  1. Erstellen und Konfigurieren einer Microsoft Entra-App für die Authentifizierung
  2. Einrichten einer GraphQL-Beispiel-API in Fabric mit Daten zum Abfragen
  3. Klonen und Konfigurieren einer vollständigen React-Anwendung von GitHub
  4. Testen der authentifizierten Verbindung

Das Lernprogramm verwendet React, aber Authentifizierungskonzepte gelten für jede Sprache. Beispiele in C#, Python oder anderen Sprachen finden Sie im GitHub-Repository von Microsoft Fabric-Beispielen.

Wer Anwendungen verbinden muss

Die Einrichtung der Anwendungsverbindung ist für Folgendes unerlässlich:

  • Web- und mobile Entwickler erstellen Anwendungen, die Daten aus Fabric Lakehouses und Warehouses nutzen
  • Integrationsentwickler verbinden Fabric-Daten mit benutzerdefinierten Anwendungen und automatisierten Workflows
  • Back-End-Entwickler erstellen Dienste, die in die einheitliche Analyseplattform von Fabric integriert werden
  • Datentechniker richten automatisierte Datenverarbeitungsworkflows ein, die Fabric-Daten über APIs nutzen

Verwenden Sie dieses Handbuch, wenn Sie Anwendungen authentifizieren und autorisieren müssen, um auf Ihre Fabric GraphQL-APIs zuzugreifen.

Voraussetzungen

  • Entwicklungstools: Sie benötigen Node.js (LTS-Version) und Visual Studio Code auf Ihrem Computer installiert.

  • Stellen Sie vor dem Verbinden einer Anwendung sicher, dass Sie über eine API für GraphQL in Fabric verfügen. Weitere Informationen finden Sie unter Erstellen einer API für GraphQL in Fabric und Hinzufügen von Daten.

  • Die API für GraphQL erfordert, dass Anwendungen Microsoft Entra für die Authentifizierung verwenden. Registrieren und konfigurieren Sie Ihre Anwendung, um API-Aufrufe für Fabric auszuführen. Weitere Informationen finden Sie unter Erstellen einer Microsoft Entra-App in Azure.

  • Die authentifizierten Anmeldeinformationen (Benutzerprinzipal, Dienstprinzipal oder verwaltete Identität), die die API aufrufen, benötigen Execute-Berechtigungen für die GraphQL-API (Option "Abfragen ausführen und Mutationen" beim Hinzufügen von direkten Zugriffsberechtigungen). Wenn Sie einmaliges Anmelden (Single Sign-On, SSO) als Verbindungsoption in der API verwenden, stellen Sie sicher, dass die Anmeldeinformationen über Lese- oder Schreibberechtigungen in der ausgewählten Datenquelle verfügen. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einer Datenquelle und Erstellen Ihres Schemas.

Zusammenfassung der Authentifizierung und Berechtigungen

Der Zugriff auf die GraphQL-API erfordert sowohl auf API-Ebene als auch auf der zugrunde liegenden Datenquellenebene eine ordnungsgemäße Authentifizierung und Autorisierung. Sie können sich entweder mit einem Benutzerprinzipal (der einen einzelnen Benutzer darstellt) oder einem Dienstprinzipal (der eine Anwendung oder einen Dienst darstellt) authentifizieren. Für die Datenquellenkonnektivität können Sie einmaliges Anmelden (Single Sign-On, SSO) verwenden, bei dem die Identität des Aufrufers an die Datenquelle übergeben wird, oder gespeicherte Anmeldeinformationen , bei denen eine vorkonfigurierte Verbindung verwendet wird.

In der folgenden Tabelle sind die verschiedenen unterstützten Authentifizierungsszenarien und die mindestens erforderlichen Berechtigungen für Clients zusammengefasst, die auf die GraphQL-API zugreifen:

API-Aufrufer Datenquellenkonnektivität Erforderliche GraphQL-API-Berechtigungen Erforderliche Datenquellenberechtigungen Microsoft Entra-App-Bereich
Benutzerprinzipal (User Principal Name, UPN) Einmaliges Anmelden (Single Sign-On, SSO) Abfragen und Mutationen ausführen auf API-Ebene Entsprechende Lese-/Schreibberechtigungen, die dem UPN für die Datenquelle gewährt werden GraphQLApi.Execute.All
Dienstprinzipal (Service Principal Name, SPN) Einmaliges Anmelden (Single Sign-On, SSO) Abfragen und Mutationen ausführen auf API-Ebene Entsprechende Lese-/Schreibberechtigungen, die dem SPN für die Datenquelle gewährt werden Nicht zutreffend
Benutzerprinzipal (User Principal Name, UPN) Gespeicherte Anmeldeinformationen Abfragen und Mutationen ausführen auf API-Ebene Entsprechende Lese-/Schreibberechtigungen, die den gespeicherten Anmeldeinformationen (Verbindung) für die Datenquelle gewährt werden GraphQLApi.Execute.All
Dienstprinzipal (Service Principal Name, SPN) Gespeicherte Anmeldeinformationen Abfragen und Mutationen ausführen auf API-Ebene Entsprechende Lese-/Schreibberechtigungen, die dem SPN für die Datenquelle gewährt werden Nicht zutreffend

Erstellen einer Microsoft Entra-App

Bevor Ihre Anwendung die Fabric GraphQL-API aufrufen kann, müssen Sie sie in der Microsoft Entra-ID registrieren. Diese Registrierung erstellt eine Identität für Ihre Anwendung und definiert, welche Berechtigungen sie benötigt. Der Registrierungsprozess generiert eine Client-ID (Anwendungs-ID) und richtet den Authentifizierungsfluss ein, den Ihre App zum Abrufen von Zugriffstoken verwendet.

Für React-Anwendungen konfigurieren Sie Einzelseitenanwendungseinstellungen (Single Page Application, SPA), die den PKCE-Fluss verwenden– eine sichere Authentifizierungsmethode, die für browserbasierte Apps entwickelt wurde, bei denen geheime Clientschlüssel nicht sicher gespeichert werden können.

  1. Registrieren Sie eine Anwendung mithilfe der schritte, die unter Schnellstart beschrieben werden: Registrieren Sie eine Anwendung bei der Microsoft Identity Platform.

  2. Die Werte der Microsoft Entra Anwendungs-ID (Client) und der Verzeichnis-ID (Mandant) werden im Feld "Zusammenfassung" angezeigt. Notieren Sie diese Werte, da Sie sie benötigen, wenn Sie die React-Anwendung konfigurieren.

  3. Konfigurieren Sie API-Berechtigungen, damit Ihre Anwendung auf die Fabric GraphQL-API zugreifen kann. Wählen Sie in der Liste Verwalten die Option API-Berechtigungen und dann Berechtigung hinzufügen aus.

  4. Fügen Sie den PowerBI-Dienst hinzu, wählen Sie delegierte Berechtigungen und dann GraphQLApi.Execute.All-Berechtigungen aus. Mit dieser Berechtigung kann Ihre Anwendung Abfragen und Mutationen im Namen des angemeldeten Benutzers ausführen. Bestätigen Sie, dass die Administratorzustimmung nicht erforderlich ist.

  5. Wechseln Sie zurück zur Verwalten Liste, wählen Sie Authentifizierung>, Eine Plattform hinzufügen>, Einzelseitenanwendung aus.

  6. Fügen Sie für lokale Entwicklungszwecke http://localhost:3000 unter Umleitungs-URIs hinzu, und bestätigen Sie, dass die Anwendung für den Autorisierungscodeflow mit PKCE (Proof Key for Code Exchange, Prüfschlüssel für den Codeaustausch) aktiviert ist. Wählen Sie die Schaltfläche Konfigurieren aus, um Ihre Änderungen zu speichern. Wenn bei der Anwendung ein Fehler im Zusammenhang mit ursprungsübergreifenden Anforderungen auftritt, fügen Sie die Plattform für Mobile- und Desktopanwendungen im vorherigen Schritt mit demselben Umleitungs-URI hinzu.

  7. Scrollen Sie unter Authentifizierung nach unten zu Erweiterte Einstellungen, und wählen Sie unter Öffentliche Clientflows zulassen die Option Ja für Folgende Mobilgerät- und Desktopflows aktivieren aus.

Einrichten einer GraphQL-Beispiel-API für den Anwendungszugriff

Wenn Ihre Microsoft Entra-App registriert ist, benötigen Sie eine GraphQL-API in Fabric, um abfragen zu können. Dieser Abschnitt führt Sie durch das Erstellen einer Beispiel-API mithilfe des Datasets für öffentliche Feiertage von Fabric. Dadurch erhalten Sie eine funktionierende API zum Testen der Authentifizierung und des Datenabrufs, ohne Ihre eigenen Datenquellen konfigurieren zu müssen.

Die Beispiel-API macht Feiertagsdaten aus einer Lakehouse-Tabelle verfügbar, die Ihre React-Anwendung zum Anzeigen von Feiertagen abfragt.

  1. Wählen Sie auf der Startseite des Fabric-Portals Datentechnik aus der Liste der Workloads aus.

  2. Wählen Sie in der Daten-Engineering-Umgebung die Option Beispiel verwenden aus und dann unter Lakehouse die Option öffentliche Feiertage, um automatisch ein neues Lakehouse mit Daten zu öffentlichen Feiertagen zu erstellen.

    Screenshot zum Auswählen der Beispieldaten-Lakehouse-Option.

  3. Führen Sie die Schritte aus der Erstellung einer API für GraphQL aus, um eine neue GraphQL-API zu erstellen und das von Ihnen erstellte Lakehouse auszuwählen. Fügen Sie die Tabelle "Feiertage" hinzu, damit Clients auf diese Daten zugreifen können.

    Screenshot vom Hinzufügen des Beispiel-Lakehouse als GraphQL-Datenquelle.

  4. Stellen Sie vor dem Erstellen der React-Anwendung sicher, dass Ihre API ordnungsgemäß funktioniert, indem Sie sie im API-Editor testen. Verwenden Sie die folgende Abfrage– dies ist die gleiche Abfrage, die Ihre React-Anwendung später ausführt:

     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. Wählen Sie auf der Symbolleiste des API-Elements Endpunkt kopieren aus.

    Screenshot der Symbolleistenoptionen für ein API-Element.

  6. Wählen Sie auf dem Bildschirm Link kopieren die Option Kopieren aus.

    Screenshot des Dialogfelds

  7. Notieren Sie die Client-ID und die Mandanten-ID aus der Microsoft Entra-App und dem Endpunkt-URI. Sie benötigen diese Werte, wenn Sie die React-Anwendung konfigurieren.

Klonen und Konfigurieren der React-Anwendung

Nachdem Sie nun die Microsoft Entra-App und die GraphQL-API eingerichtet haben, können Sie eine React-Anwendung konfigurieren, um eine Verbindung mit ihnen herzustellen. Die Anwendung verwendet microsoft Authentication Library (MSAL), um die Authentifizierung zu verarbeiten und GraphQL-Anforderungen mit Bearer-Token zu erstellen.

  1. Klonen Sie das Beispiel-Repository von GitHub:

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

  2. Navigieren Sie zum React-Anwendungsordner:

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

    Der Ordner enthält eine vollständige React-Anwendung. Sie müssen nur bearbeiten src/authConfig.js , um Ihren spezifischen Endpunkt und Ihre Anmeldeinformationen zu konfigurieren.

  3. Öffnen Sie das Projekt in Ihrem Code-Editor:

    code .

  4. Navigieren Sie in Ihrem Editor zu dem src Ordner, und öffnen Sie authConfig.jsden Ordner.

  5. Ersetzen Sie die folgenden Platzhalterwerte durch Ihre spezifischen Details:

    Von Bedeutung

    In derselben Datei enthält die loginRequest Konstante den Bereich https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Dieser genaue Bereich ist für den Zugriff auf Fabric GraphQL-APIs erforderlich. Entfernen oder ändern Sie diesen Bereich nicht; andernfalls schlägt die Authentifizierung fehl.

  6. Speichern Sie die Datei.

  7. Navigieren Sie in Ihrem Terminal zum Projektstammordner, und führen Sie Folgendes aus:

    npm install

    Dadurch werden alle erforderlichen Abhängigkeiten installiert.

Testen der App

Führen Sie die Anwendung lokal aus, um zu überprüfen, ob alles ordnungsgemäß funktioniert:

  1. Führen Sie in Ihrem Terminal Folgendes aus:

    npm start

    Dieser Befehl startet den Entwicklungsserver und öffnet die Anwendung in Ihrem Browser.

  2. Schließen Sie den Authentifizierungsprozess ab, wenn die Anwendung an http://localhost:3000 geladen ist. Führen Sie die im Lernprogrammabschnitt beschriebenen Anmeldeschritte aus, um die API aus der Anwendung aufzurufen.

  3. Nachdem Sie sich erfolgreich angemeldet haben, wählen Sie die Schaltfläche Fabric-API für GraphQL-Abfrage aus. Dadurch wird der Authentifizierungsfluss ausgelöst, ein Zugriffstoken abgerufen und die GraphQL-Abfrage für Ihre Fabric-API ausgeführt.

    Screenshot der React-Beispiel-App nach der Anmeldung.

  4. Wenn alles ordnungsgemäß konfiguriert ist, zeigt die Anwendung feiertage in einer Tabelle an. Dies bestätigt, dass:

    • Ihre Microsoft Entra-App verfügt über die richtigen Berechtigungen.
    • Das Zugriffstoken wurde erfolgreich erworben.
    • Die GraphQL-API authentifizierte die Anforderung.
    • Die Abfrage, die für die Lakehouse-Daten ausgeführt wird

    Screenshot der React-Beispiel-App nach Erhalt der GraphQL-Anforderung.

Andere npm-Befehle

Darüber hinaus können Sie die folgenden allgemeinen npm-Befehle für verschiedene Entwicklungsszenarien verwenden: npm start und npm install

  • npm run dev - Alternative Methode zum Starten des Entwicklungsservers
  • npm run build – Erstellen eines optimierten Produktionsbuilds Ihrer Anwendung
  • npm run preview – Testen Sie die Produktionsversion lokal, bevor Sie diese bereitstellen
  • npm test - Ausführen von automatisierten Tests, um sicherzustellen, dass Ihr Code ordnungsgemäß funktioniert

Verwandte Inhalte

Nachdem Sie nun eine funktionierende Anwendung mit Ihrer Fabric GraphQL-API verbunden haben, erkunden Sie diese Ressourcen, um anspruchsvollere Lösungen zu erstellen:

  • Last updated on