Verbinden von Anwendungen mit Fabric API für GraphQL
Hinweis
Die Microsoft Fabric-API für GraphQL befindet sich in der Vorschau.
Um eine Anwendung mit einer API für GraphQL zu verbinden, benötigen Sie drei wichtige Informationen: eine Client-ID, Ihre Mandanten-ID und Ihre GraphQL-Endpunktadresse in Fabric. In den folgenden Abschnitten wird gezeigt, wie Sie alle benötigten Details erstellen und abrufen und wie Sie mit einer Beispielanwendung auf Ihre API zugreifen können.
Voraussetzungen
Derzeit erfordert die API für GraphQL, dass Anwendungen Microsoft Entra für die Authentifizierung verwenden. Ihre Anwendung muss registriert und entsprechend konfiguriert werden, um API-Aufrufe für Fabric auszuführen. Weitere Informationen finden Sie unter Erstellen einer Microsoft Entra-App in Azure.
Der authentifizierte Benutzer, der die API aufruft, muss ein Mitglied des Arbeitsbereichs sein, in dem sich sowohl die API- als auch die Datenquellenelemente mit einer Mitwirkendenrolle befinden. Weitere Informationen finden Sie unter Gewähren des Zugriffs auf Arbeitsbereiche für Benutzer.
Bevor Sie eine Anwendung verbinden, müssen Sie eine API für GraphQL in Fabric erstellen. Weitere Informationen finden Sie unter Erstellen einer API für GraphQL in Fabric und Hinzufügen von Daten.
Erstellen Sie eine Microsoft Entra-App
In den folgenden Schritten wird gezeigt, wie die Unterstützung für eine ReactJS-Anwendung in Microsoft Entra konfiguriert wird.
Melden Sie sich beim Azure-Portal an.
Suchen Sie nach Microsoft Entra ID, und wählen Sie es aus.
Wählen Sie in der Liste Verwalten die Option App-Registrierung aus.
Wählen Sie Neue Registrierung aus.
Füllen Sie die erforderlichen Informationen aus:
Name – Geben Sie einen Namen für Ihre Anwendung ein.
Unterstützte Kontotypen: Wählen Sie aus, welche Konten von Ihrer Anwendung unterstützt werden sollen.
(Optional) Umleitungs-URI – Geben Sie bei Bedarf einen URI ein.
Wählen Sie Registrieren aus. Die Werte App-ID (Client) und Verzeichnis-ID (Mandant) Ihrer Microsoft Entra-App-Anwendung werden im Feld „Zusammenfassung“ angezeigt. Notieren Sie diese Werte, da sie später erforderlich sind.
Wählen Sie in der Liste Verwalten die Option API-Berechtigungen und dann Berechtigung hinzufügen aus.
Fügen Sie den PowerBI-Dienst hinzu, und wählen Sie Delegierte Berechtigungen und dann die Berechtigung Item.Execute.All aus. Stellen Sie sicher, dass keine Administratoreinwilligung erforderlich ist.
Wählen Sie in der Liste Verwalten die Option Authentifizierung>Plattform hinzufügen>Single-Page-Webanwendung aus.
Fügen Sie für lokale Entwicklungszwecke
http://localhost:3000unter Umleitungs-URIs hinzu, und bestätigen Sie, dass die Anwendung für den Autorisierungscodefluss 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 Falls die Anwendung eine Fehlermeldung im Zusammenhang mit ursprungsübergreifenden Anforderungen (Cross-Origin Requests, CORS) erhält, fügen Sie die Plattform für mobile und Desktopanwendungen im vorherigen Schritt mit demselben Umleitungs-URI hinzu.Scrollen Sie unter Autorisierung nach unten zu Erweiterte Einstellungen, und wählen Sie unter Öffentliche Clientflows zulassen die Option Ja für Folgende Mobilgerät- und Desktop-Flows aktivieren aus.
Einrichten einer GraphQL-Beispiel-API für den Anwendungszugriff
In diesem Beispiel erstellen wir eine GraphQL-API, um Beispiel-Lakehouse-Daten für Clients verfügbar zu machen.
Wählen Sie auf der Startseite des Fabric-Portals Datentechnik aus der Liste der Workloads aus.
Wählen Sie in der Oberfläche Datentechnik die Option Beispiel verwenden und unter Lakehouse die Option Feiertage aus, um automatisch ein neues Lakehouse mit Daten zu Feiertagen zu erstellen.
Erstellen Sie mit den Schritten aus Erstellen einer API für GraphQL eine neue GraphQL-API, und wählen Sie das von Ihnen erstellte Lakehouse aus. Fügen Sie die Tabelle „Feiertage“ hinzu, damit die Clients auf diese Daten zugreifen können.
Testen Sie die GraphQL-API im API-Editor mithilfe der folgenden Beispielabfrage. Es ist die gleiche Abfrage, die wir in unserer React-Clientanwendung verwenden:
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 } } }Wählen Sie auf der Symbolleiste des API-Elements Endpunkt kopieren aus.
Wählen Sie im Dialogfeld Link kopieren die Option Kopieren aus.
Kopieren Sie den Endpunkt-URI (wird später benötigt) für die zuvor aufgezeichnete Client-ID und Mandanten-ID aus der Microsoft Entra-App.
Konfigurieren einer React-App für den Zugriff auf die Feiertags-API
Wir verwenden eine vorhandene React-App als Ausgangspunkt. Führen Sie alle Schritte im Tutorial Erstellen einer React-SPA und Vorbereiten der Anwendung für die Authentifizierung aus, um ein React-Projekt mit bereits konfigurierter Microsoft Entra-Authentifizierung zu erstellen, einschließlich zusätzlicher Dateien und Ordner, die der Projektstruktur hinzugefügt werden müssen. Wir müssen nur drei Dateien ändern, um die App für unseren GraphQL-Anwendungsfall anzupassen.
Öffnen Sie im Ordner src die Datei authConfig.js, und ersetzen Sie den Inhalt der Datei durch den folgenden Codeausschnitt:
/* * 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"] }; /** * 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", };Wie Sie im obigen Code sehen können, ist es wichtig, den richtigen Bereich für den Zugriff auf die Anwendung zu verwenden. In unserem Fall wird
https://analysis.windows.net/powerbi/api/Item.Execute.Allverwendet.Wichtig
Bereiche können sich während der Microsoft Fabric-API für die GraphQL-Vorschau ändern.
Ersetzen Sie die folgenden Werte durch die Werte aus dem Microsoft Entra Admin Center.
clientId– Der Bezeichner der Anwendung, auch Client genannt. Ersetzen SieEnter_the_Application_Id_Heredurch den Wert für Anwendungs-ID (Client), den Sie zuvor von der Übersichtsseite der registrierten Microsoft Entra-Anwendung notiert haben.authority– Diese besteht aus zwei Teilen:- Die Instanz ist der Endpunkt des Cloudanbieters. Überprüfen Sie die verschiedenen verfügbaren Endpunkte unter Nationale Clouds.
- Die Mandanten-ID ist der Bezeichner des Mandanten, in dem die Anwendung registriert ist. Ersetzen Sie Enter_the_Tenant_Info_Here durch den Wert der Verzeichnis-ID (Mandanten-ID), die zuvor auf der Übersichtsseite der registrierten Anwendung aufgezeichnet wurde.
graphQLEndpoint: Die Fabric-API für den GraphQL-Endpunkt. Ersetzen SieEnter_the_GraphQL_Endpoint_Heredurch den zuvor aufgezeichneten GraphQL-API-Endpunkt.
Speichern Sie die Datei .
Öffnen Sie im Ordner src die Datei App.js, und ersetzen Sie den Inhalt der Datei durch den folgenden Codeausschnitt.
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> ); }Speichern Sie die Datei .
Öffnen Sie im Ordner src/components die Datei ProfileData.jsx, und ersetzen Sie den Inhalt der Datei durch den folgenden Codeausschnitt:
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> )};Speichern Sie alle Dateiänderungen.
Wechseln Sie in der Terminalanwendung Ihrer Wahl zum Stammordner des React-Projekts, und führen Sie den Befehl
npm startaus, um die Anwendung lokal zu testen.Nachdem die Anwendung in Ihrem Browser von
http://localhost:3000geladen wurde, führen Sie die Schritte im letzten Teil des Lernprogramms Aufrufen der API aus der Anwendung auf, um sich zu authentifizieren.Klicken Sie nach der Anmeldung auf die Schaltfläche Abfragen der Fabric-API für GraphQL-Daten.
Eine erfolgreich authentifizierte Anforderung an die GraphQL-API in Fabric gibt die Daten aus der GraphQL-Abfrage an das Lakehouse in unserer React-Clientanwendung zurück:
Verwenden eines Dienstprinzipals
Die Schritte im vorherigen Abschnitt sind erforderlich, um Zugriff auf Benutzerprinzipale zu ermöglichen. Es ist jedoch auch möglich, mit einem Dienstprinzipal auf die GraphQL-API zuzugreifen:
Führen Sie die Schritte im vorherigen Abschnitt aus, um eine zweite Microsoft Entra-App mit ähnlichen Berechtigungen (Bereich Item.Execute.All für den PowerBI-Dienst) zu erstellen. Fügen Sie in der neuen App unter Zertifikate und Geheimnisse einen geheimen Clientschlüssel hinzu. Weitere Informationen finden Sie unter Registrieren einer Microsoft Entra-App und Erstellen eines Dienstprinzipals.
Stellen Sie sicher, dass Mandantenadministratoren die Verwendung von Dienstprinzipalen in Fabric aktiviert haben. Wechseln Sie im Mandantenadministratorportal zu Mandanteneinstellungen. Erweitern Sie unter Entwicklereinstellungen den Abschnitt Dienstprinzipale können Fabric-APIs verwenden.. Wenn diese Einstellung aktiviert ist, wird die Anwendung im Fabric-Portal für die Rollen- oder Berechtigungszuweisung angezeigt. Weitere Informationen finden Sie unter Unterstützung für Identitäten.
Der Dienstprinzipal benötigt Zugriff auf die GraphQL-API und die Datenquelle, genauer gesagt die Berechtigung Ausführen für die GraphQL-API und Lese- oder Schreibzugriff auf die ausgewählte Datenquelle. Öffnen Sie im Fabric-Portal den Arbeitsbereich, und wählen Sie die Auslassungspunkte neben der API aus. Wählen Sie Berechtigungen verwalten für die API und dann Benutzer hinzufügen aus. Fügen Sie die Anwendung hinzu, und wählen Sie Abfragen und Mutationen ausführen aus. Dadurch wird dem Dienstprinzipal die erforderliche Berechtigung Ausführen gewährt. Zu Testzwecken ist es am einfachsten, die erforderlichen Berechtigungen sowohl für die API als auch für die Datenquelle zu implementieren, indem Sie die Anwendung als Arbeitsbereichsmitglied mit der Rolle „Mitwirkender“ hinzufügen,in der sich sowohl die GraphQL-API als auch Datenquellenelemente befinden.
Wichtig
Stellen Sie beim Definieren der Konnektivitätsoption für Ihre API sicher, dass die API für die Verwendung des einmaligen Anmeldens (Single Sign-On, SSO) konfiguriert ist. Derzeit unterstützen Dienstprinzipale keine gespeicherten Anmeldeinformationen. Weitere Informationen finden Sie unter Erstellen einer API für GraphQL in Fabric und Hinzufügen von Daten.
Da ein Dienstprinzipal entweder ein Zertifikat oder einen geheimen Clientschlüssel erfordert, wird er von der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) in Single-Page-Webanwendungen (SPAs) wie der im letzten Schritt erstellten React-App nicht unterstützt. Sie können einen ordnungsgemäß geschützten Back-End-Dienst je nach Ihren Anforderungen und Anwendungsfällen mit klar definierter Autorisierungslogik nutzen.
Nachdem Ihre API für den Zugriff durch einen Dienstprinzipal konfiguriert wurde, können Sie sie lokal mithilfe einer einfachen Node.JS-Anwendung auf Ihrem lokalen Computer testen:
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);
}
}
Nachdem Sie die Abhängigkeiten (@azure/identity) mit Ihrem Node.JS-Paket-Manager installiert, die Datei mit den erforderlichen Informationen geändert und sie gespeichert und ausgeführt haben (node <filename.js>), können Sie ein Token von Microsoft Entra abrufen.
Das Token kann dann verwendet werden, um Ihre GraphQL-API mithilfe von PowerShell aufzurufen. Ersetzen Sie dazu die entsprechenden Details durch das eben abgerufene Token, die GraphQL-Abfrage, die Sie ausführen möchten, und den GraphQL-API-Endpunkt:
$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
Alternativ können Sie cURL verwenden, um das gleiche Ergebnis zu erzielen:
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)>"}'
Zu lokalen Testzwecken kann der Node.JS-Code mit einer zusätzlichen Abhängigkeit (axios) leicht geändert werden, um das Token abzurufen und die API in einer einzigen Ausführung aufzurufen:
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();
Andere Sprachen
Hier findest du C#-, Python- und andere Sprachbeispiele zum Herstellen einer Verbindung mit deiner GraphQL-API im GitHub-Repository von Microsoft Fabric Samples.