Opret forbindelse mellem programmer og Fabric API til GraphQL
Hvis du vil forbinde et program til en API til GraphQL, skal du bruge tre vigtige oplysninger: et klient-id, dit lejer-id og din GraphQL-slutpunktsadresse i Fabric. I de følgende afsnit viser vi, hvordan du opretter og henter alle de oplysninger, du har brug for, og hvordan du får adgang til din API ved hjælp af et eksempelprogram.
Forudsætninger
API til GraphQL kræver i øjeblikket, at programmer bruger Microsoft Entra til godkendelse. Dit program skal registreres og konfigureres korrekt for at kunne udføre API-kald mod Fabric. Du kan få flere oplysninger under Opret en Microsoft Entra-app i Azure.
Den godkendte bruger, der kalder API'en, kræver Udfør-tilladelser til GraphQL-API'en (kør forespørgsler og mutationer, når du tilføjer direkte adgangstilladelser), og hvis du bruger Enkelt sing-on (SSO) som forbindelsesindstilling i API'en, kræves læse- eller skrivetilladelser i den valgte datakilde i overensstemmelse hermed. Du kan få flere oplysninger under Opret forbindelse til en datakilde, og opret dit skema.
Før du opretter forbindelse til et program, skal du have en API til GraphQL i Fabric. Du kan få flere oplysninger under Opret en API til GraphQL i Fabric, og tilføj data.
Opret en Microsoft Entra-app
I følgende trin viser vi, hvordan du konfigurerer understøttelse af et ReactJS-program i Microsoft Entra.
- Registrer et program ved hjælp af de trin, der er beskrevet i Hurtig start: Registrer et program med Microsoft-identitetsplatformen.
- Værdierne for dit Microsoft Entra-appprogram (klient) id og mappe-id (lejer) vises i feltet Oversigt. Registrer disse værdier, som de er påkrævet senere.
- På listen Administrer skal du vælge API-tilladelserog derefter Tilføj tilladelse.
- Tilføj PowerBI-tjenesten, vælg Delegerede tilladelser, og vælg Item.Execute.All permissions. Sørg for, at administratorsamtykke ikke er påkrævet.
- Tilbage til listen Administrer skal du vælge Godkendelse>Tilføj en platform, >enkeltsidet program.
- I forbindelse med lokal udvikling skal du tilføje
http://localhost:3000
under Omdirigerings-URI'er og bekræfte, at programmet er aktiveret for godkendelseskodeflowet med proof key for Code Exchange (PKCE). Vælg knappen Konfigurer for at gemme dine ændringer. Hvis programmet modtager en fejl, der er relateret til anmodninger på tværs af oprindelser, skal du tilføje platformen mobil- og skrivebordsprogrammer i det forrige trin med den samme omdirigerings-URI. - Gå tilbage til Godkendelse, rul ned til avancerede indstillinger, og under Tillad offentlige klientflowskal du vælge Ja for at Aktivér følgendepå mobilenheder og stationære computere .
Konfigurer en GraphQL-eksempel-API til programadgang
I dette eksempel opretter vi en GraphQL-API for at vise lakehouse-eksempeldata for klienter.
Vælg Dataudvikler på listen over arbejdsbelastninger på startsiden for Fabric-portalen.
I Dataudvikler skal du vælge Brug et eksempel, og under Lakehouse skal du vælge Helligdage for automatisk at oprette et nyt Lakehouse med helligdage.
Når du følger trinnene fra Opret en API til GraphQL, skal du oprette en ny GraphQL-API og vælge det Lakehouse, du har oprettet. Tilføj tabellen helligdage for at give klienterne adgang til disse data.
Test GraphQL-API'en i API-editoren ved hjælp af følgende eksempelforespørgsel. Det er den samme forespørgsel, vi bruger i vores React-klientprogram:
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 } } }
Vælg Kopiér slutpunkt på API-elementets værktøjslinje.
Vælg Kopiér på skærmen Kopiér link.
Som klient-id og lejer-id fra Microsoft Entra-appen, der er registreret tidligere, skal du kopiere slutpunktets URI, som det er påkrævet senere.
Konfigurer en React-app for at få adgang til API'en for helligdage
Vi bruger en eksisterende React-app som udgangspunkt. Følg alle trinnene i selvstudiet Opret et React-enkeltsidet program, og forbered det til godkendelse for at oprette et React-projekt, hvor Microsoft Entra-godkendelse allerede er konfigureret, herunder yderligere filer og mapper, der skal føjes til projektstrukturen. Vi behøver kun at ændre tre filer for at tilpasse appen til vores GraphQL-brugscase.
Åbn filen authConfig.js i mappen src, og erstat indholdet af filen med følgende kodestykke:
/* * 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", };
Som du kan se i ovenstående kode, er det vigtigt at bruge det korrekte område til at få adgang til programmet. I vores tilfælde
https://analysis.windows.net/powerbi/api/Item.Execute.All
.Vigtigt
Områder kan blive ændret under Microsoft Fabric API til GraphQL-prøveversion.
Erstat følgende værdier med værdierne fra Microsoft Entra Administration.
-
clientId
- Programmets id, også kaldet klienten. ErstatEnter_the_Application_Id_Here
med den program-id-værdi (klient), der blev registreret tidligere fra oversigtssiden for det registrerede Microsoft Entra-program. -
authority
- Dette består af to dele:- Forekomsten er slutpunktet for cloududbyderen. Kontakt de forskellige tilgængelige slutpunkter i nationale cloudmiljøer.
- Lejer-id'et er id'et for den lejer, hvor programmet er registreret. Erstat Enter_the_Tenant_Info_Here med den mappe-id-værdi (lejer), der blev registreret tidligere fra oversigtssiden for det registrerede program.
-
graphQLEndpoint
– Fabric API til GraphQL-slutpunktet. ErstatEnter_the_GraphQL_Endpoint_Here
med GraphQL API-slutpunktet, der er registreret tidligere.
-
Gem filen.
Åbn App.js-fileni den samme src-mappe, og erstat indholdet af filen med følgende kodestykke:
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> ); }
Gem filen.
Til sidst skal du åbne filen ProfileData.jsx under mappen src/components og erstatte indholdet af filen med følgende kodestykke:
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> )};
Gem alle filændringerne.
I den valgte terminalanvendelse skal du gå til rodmappen for React-projektet og udføre kommandoen
npm start
for at teste programmet lokalt.Når programmet indlæses i din browser fra
http://localhost:3000
, skal du følge trinnene i den sidste del af selvstudiet Kald API'en fra programmet for at godkende.Når du har logget på, skal du klikke på knappen Query Fabric API til GraphQL-data.
En godkendt anmodning til GraphQL-API'en i Fabric returnerer dataene fra GraphQL-forespørgslen til Lakehouse i vores React-klientprogram:
Brug en tjenesteprincipal
Selvom trinnene i forrige afsnit er påkrævet for at give adgang til brugerprincipaler, er det også muligt at få adgang til GraphQL-API'en med en tjenesteprincipal:
Følg trinnene i forrige afsnit for at oprette endnu en Microsoft Entra-app med lignende tilladelser (Item.Execute.All-området for PowerBI-tjenesten). I den nye app skal du tilføje en klienthemmelighed under Certifikater og hemmeligheder for at få flere oplysninger under Registrer en Microsoft Entra-app, og opret en tjenesteprincipal.
Sørg for, at lejeradministratorer har aktiveret brugen af tjenesteprincipaler i Fabric. Gå til Lejerindstillinger på lejeradministrationsportalen. Under Udviklerindstillinger kan tjenesteprincipaler bruge Fabric-API'er. Når denne indstilling er aktiveret, vil programmet være synligt i Fabric Portal for tildeling af roller eller tilladelser. Du kan finde flere oplysninger om identitetssupport.
Tjenesteprincipalen skal have adgang til både GraphQL-API'en og datakilden, mere specifikt tilladelsen Udfør til GraphQL-API'en og læse- eller skriveadgang, der kræves i den valgte datakilde i overensstemmelse hermed. Åbn arbejdsområdet i Fabric Portal, og vælg ellipsen ud for API. Vælg Administrer tilladelser for API'en og derefter Tilføj bruger. Tilføj programmet, og vælg Kør forespørgsler og mutationer, som giver de påkrævede Udfør-tilladelser til tjenesteprincipalen. Til testformål er den nemmeste måde at implementere de påkrævede tilladelser for både API'en og datakilden på ved at tilføje programmet som medlem af arbejdsområdet med en bidragyderrolle, hvor både GraphQL-API'en og datakildeelementerne er placeret.
Vigtigt
Når du definerer forbindelsesindstillingen for din API, skal du sørge for, at API'en er konfigureret til at bruge enkeltlogon (SSO). Tjenesteprincipaler understøtter i øjeblikket ikke gemte legitimationsoplysninger. Du kan få flere oplysninger under Opret en API til GraphQL i Fabric, og tilføj data
Da en tjenesteprincipal kræver enten et certifikat eller en klienthemmelighed, understøttes det ikke af Microsoft Authentication Library (MSAL) i enkeltsidede programmer (SPA'er), f.eks. React-appen, som vi byggede i det sidste trin. Du kan udnytte en backendtjeneste, der er korrekt sikret med veldefineret godkendelseslogik, afhængigt af dine krav og use cases.
Når din API er konfigureret til at blive åbnet af en tjenesteprincipal, kan du teste den lokalt ved hjælp af et simpelt Node.JS program på din lokale computer:
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);
}
}
Når du har installeret afhængighederne (@azure/identity
) med din foretrukne Node.JS pakkestyring, ændret filen med de påkrævede oplysninger, gemt og kørt den (node <filename.js>
), kan du hente et token fra Microsoft Entra.
Tokenet kan derefter bruges til at aktivere din GraphQL-API ved hjælp af PowerShell ved at erstatte de relevante oplysninger med det token, du lige har hentet, den GraphQL-forespørgsel, du vil udføre, og GraphQL API-slutpunktet:
$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
Du kan også bruge cURL til at opnå det samme resultat:
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)>"}'
I forbindelse med lokale test kan den Node.JS kode ændres en smule med en ekstra afhængighed (axios
) for at hente tokenet og aktivere API'en i en enkelt udførelse:
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();
Andre sprog
Find eksempler på C#, Python og andre sprog for at oprette forbindelse til din GraphQL-API i GitHub-lageret til Microsoft Fabric Samples.