Alkalmazások csatlakoztatása a Fabric API-hoz a GraphQL-hez

Cikk
10/25/2024

Feljegyzés

A GraphQL-hez készült Microsoft Fabric API előzetes verzióban érhető el.

Az alkalmazások GraphQL-hez készült API-hoz való csatlakoztatásához három fontos információra van szüksége: egy ügyfél-azonosítóra, a bérlőazonosítóra és a GraphQL-végpont címére a Fabricben. A következő szakaszokban bemutatjuk, hogyan hozhat létre és kérdezhet le minden szükséges adatot, és hogyan érheti el az API-t egy mintaalkalmazás használatával.

Előfeltételek

A GraphQL API jelenleg megköveteli, hogy az alkalmazások a Microsoft Entrát használják a hitelesítéshez. Az alkalmazást megfelelően kell regisztrálni és konfigurálni ahhoz, hogy API-hívásokat hajt végre a Fabricen. További információ: Microsoft Entra-alkalmazás létrehozása az Azure-ban.
Az API-t hívó hitelesített felhasználónak munkaterületi tagnak kell lennie, ahol az API és az adatforrás elemei közreműködői szerepkörrel vannak elosztva. További információt a munkaterületekhez való hozzáférés biztosítása a felhasználóknak című témakörben talál.
Mielőtt csatlakoztat egy alkalmazást, rendelkeznie kell egy API-val a GraphQL-hez a Fabricben. További információ: API létrehozása a GraphQL-hez a Fabricben, és adatok hozzáadása.

Microsoft Entra alkalmazás létrehozása

Az alábbi lépésekben bemutatjuk, hogyan konfigurálhatja a ReactJS-alkalmazások támogatását a Microsoft Entra-ban.

Jelentkezzen be az Azure Portalra.
Keresse meg és válassza ki a Microsoft Entra ID-t.
A Kezelés listában válassza az Alkalmazásregisztráció lehetőséget.
Új regisztráció kiválasztása.
Adja meg a szükséges információkat:
- Név – Adja meg az alkalmazás nevét.
- Támogatott fióktípusok – Válassza ki azokat a fiókokat, amelyeket az alkalmazás támogatni szeretne.
- (Nem kötelező) Átirányítási URI – Szükség esetén adjon meg egy URI-t. GraphQL.Execute.All vagy Item.Execute.All
Válassza ki a pénztárgépet. A Microsoft Entra alkalmazásalkalmazás (ügyfél) azonosítója és a címtár (bérlő) azonosítója az Összegzés mezőben jelenik meg. Jegyezze fel ezeket az értékeket, ahogy később szükség van rájuk.
A Kezelés listában válassza az API-engedélyeket, majd az Engedély hozzáadása lehetőséget.
Adja hozzá a PowerBI szolgáltatást, válassza a Delegált engedélyek, majd a Datamart.ReadWrite.All engedélyeket. Győződjön meg arról, hogy nincs szükség rendszergazdai hozzájárulásra.
Térjen vissza a Kezelés listához, válassza a Hitelesítés lehetőséget, válassza a Platform hozzáadása, majd az Egyoldalas alkalmazás lehetőséget.
Helyi fejlesztési célokra adja hozzá http://localhost:3000 az Átirányítási URI-k alatt, és győződjön meg arról, hogy az alkalmazás engedélyezve van az engedélyezési kódfolyamathoz a Code Exchange-hez (PKCE) készült Proof Key billentyűvel. A módosítások mentéséhez válassza a Konfigurálás gombot. Ha az alkalmazás a forrásközi kérelmekkel kapcsolatos hibát kap, adja hozzá a Mobil és asztali alkalmazásplatformot az előző lépésben ugyanazzal az átirányítási URI-val.
Térjen vissza az engedélyezéshez, görgessen le a Speciális beállításokhoz, és a nyilvános ügyfélfolyamatok engedélyezése csoportban válassza az Igen lehetőséget az alábbi mobil- és asztali folyamatok engedélyezéséhez.

Minta GraphQL API beállítása alkalmazáshozzáféréshez

Ebben a példában létrehozunk egy GraphQL API-t, amely a Lakehouse-mintaadatokat teszi elérhetővé az ügyfelek számára.

A Háló portál kezdőlapján válassza a adatmérnök elemet a számítási feladatok listájából.
A adatmérnök felületen válassza a Minta használata lehetőséget, és a Lakehouse alatt válassza a Munkaszüneti napok lehetőséget, hogy automatikusan létrehozhasson egy új Lakehouse-t a munkaszüneti napok adataival.
A GraphQL-hez készült API létrehozásának lépéseit követve hozzon létre egy új GraphQL API-t, és válassza ki a létrehozott Lakehouse-t. Adja hozzá a munkaszüneti napok táblát, hogy az ügyfelek hozzáférhessenek ezekhez az adatokhoz.

Tesztelje a GraphQL API-t az API-szerkesztőben az alábbi mintalekérdezés használatával. Ugyanaz a lekérdezés, amelyet a React-ügyfélalkalmazásban használunk:

 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álassza a Végpont másolása lehetőséget az API-elem eszköztárán.
A Másolás hivatkozás képernyőn válassza a Másolás lehetőséget.
Mivel a Microsoft Entra alkalmazás ügyfél-azonosítója és bérlőazonosítója korábban fel van jegyezve, másolja ki a végpont URI-ját, ahogy később szükség van rá.

React-alkalmazás konfigurálása az ünnepnapok API-hoz való hozzáféréshez

Kiindulási pontként egy meglévő React-alkalmazást használunk. Kövesse az oktatóanyag összes lépését: Egyoldalas React-alkalmazás létrehozása és hitelesítésre való előkészítése a Már konfigurált Microsoft Entra-hitelesítéssel rendelkező React-projekt létrehozásához, beleértve a projektstruktúrához hozzáadandó további fájlokat és mappákat is. Csak három fájlt kell módosítanunk ahhoz, hogy az alkalmazást a GraphQL-használati esethez igazítsuk.

Az src mappában nyissa meg a authConfig.js fájlt, és cserélje le a fájl tartalmát a következő kódrészletre:

 /*
  * 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","https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.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",
 };

Ahogy a fenti kódban látható, fontos, hogy a megfelelő hatókört használja az alkalmazás eléréséhez. A mi esetünkben https://analysis.windows.net/powerbi/api/Item.Execute.All és https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All.

Fontos

A hatókörök változhatnak a GraphQL-hez készült Microsoft Fabric API előzetes verziójában.

Cserélje le a következő értékeket a Microsoft Entra Felügyeleti központ értékeire.
- clientId - Az alkalmazás azonosítója, más néven az ügyfél. Cserélje le Enter_the_Application_Id_Here a regisztrált Microsoft Entra-alkalmazás áttekintési oldaláról korábban rögzített alkalmazás-(ügyfél-) azonosító értékét.
- authority - Ez két részből áll:
  - A példány a felhőszolgáltató végpontja. Ellenőrizze a különböző elérhető végpontokat a nemzeti felhőkben.
  - A bérlőazonosító annak a bérlőnek az azonosítója, amelyben az alkalmazás regisztrálva van. Cserélje le a Enter_the_Tenant_Info_Here a címtár (bérlő) azonosítójának a regisztrált alkalmazás áttekintési oldaláról korábban rögzített értékére.
- graphQLEndpoint - A Fabric API a GraphQL-végponthoz. Cserélje le Enter_the_GraphQL_Endpoint_Here a korábban rögzített GraphQL API-végpontra.
Mentse a fájlt.

Ugyanabban az src mappában nyissa meg a App.js fájlt, és cserélje le a fájl tartalmát a következő kódrészletre:

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

Mentse a fájlt.

Végül az src/components mappa alatt nyissa meg a ProfileData.jsx fájlt, és cserélje le a fájl tartalmát a következő kódrészletre:

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

Mentse az összes fájlmódosítást.
A választott terminálalkalmazásban nyissa meg a React-projekt gyökérmappáját, és hajtsa végre a parancsot npm start az alkalmazás helyi teszteléséhez.
Miután az alkalmazás betöltődött a böngészőben http://localhost:3000, kövesse az oktatóanyag utolsó részének lépéseit, és hívja meg az API-t az alkalmazástól a hitelesítéshez.
Bejelentkezés után kattintson a GraphQL-adatok lekérdezési háló API-jára.
A GraphQL API-hoz a Fabricben való sikeres hitelesített kérés visszaadja a GraphQL-lekérdezés adatait a Lakehouse-nak a React-ügyfélalkalmazásban:

Szolgáltatásnév használata

Bár az előző szakaszban ismertetett lépések szükségesek a felhasználói tagok hozzáférésének biztosításához, a GraphQL API szolgáltatásnévvel is elérhető:

Az előző szakaszban leírt lépéseket követve hozzon létre egy második Microsoft Entra-alkalmazást. Az új alkalmazásban adjon hozzá egy titkos ügyfélkulcsot a Tanúsítványok és titkos kódok területen. További információ: Microsoft Entra-alkalmazás regisztrálása és szolgáltatásnév létrehozása.
A Bérlői felügyeleti portálon nyissa meg a Bérlői beállítások lehetőséget. A Fejlesztői beállítások területen a szolgáltatásnevek használhatják a Fabric API-kat. Ha ez a beállítás engedélyezve van, az alkalmazás látható lesz a Háló portálon a szerepkör- vagy engedély-hozzárendeléshez. További információt az identitástámogatásról talál.
A szolgáltatásnévnek hozzá kell férnie a GraphQL API-hoz és az adatforráshoz is. A Háló portálon adja hozzá az alkalmazást olyan munkaterület-tagként, amely közreműködői szerepkörrel rendelkezik, ahol a GraphQL API és az adatforráselemek is találhatók.

Mivel a szolgáltatásnév tanúsítványt vagy titkos ügyfélkulcsot igényel, a Microsoft Authentication Library (MSAL) nem támogatja az egyoldalas alkalmazásokban (SPA-kban), mint az előző lépésben létrehozott React alkalmazás. A háttérszolgáltatást a követelményektől és a használati esetektől függően megfelelően biztonságosan, jól definiált engedélyezési logikával használhatja.

Miután az API-t úgy konfigurálta, hogy egy szolgáltatásnév elérje, helyileg tesztelheti egy egyszerű Node.JS alkalmazással a helyi gépen:

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

Miután telepítette a függőségeket (@azure/identity) a választott Node.JS csomagkezelővel, módosította a fájlt a szükséges információkkal, mentette és futtatta (node <filename.js>), lekérhet egy jogkivonatot a Microsoft Entrától.

A jogkivonat ezután a GraphQL API PowerShell-lel való meghívásához használható úgy, hogy lecseréli a megfelelő részleteket az imént lekért jogkivonatra , a végrehajtani kívánt GraphQL-lekérdezésre és a GraphQL API-végpontra:

$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

Másik lehetőségként a cURL-t is használhatja ugyanahhoz az eredményhez:

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

Helyi tesztelési célokra a Node.JS kód kissé módosítható egy további függőséggel (axios) a jogkivonat lekéréséhez és az API egyetlen végrehajtásban való meghívásához:

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

További nyelvek

C#, Python és más nyelvi minták keresése a GraphQL API-hoz való csatlakozáshoz a Microsoft Fabric Samples GitHub-adattárban.

Megosztás a következőn keresztül:

Alkalmazások csatlakoztatása a Fabric API-hoz a GraphQL-hez

Előfeltételek

Microsoft Entra alkalmazás létrehozása

Minta GraphQL API beállítása alkalmazáshozzáféréshez

React-alkalmazás konfigurálása az ünnepnapok API-hoz való hozzáféréshez

Szolgáltatásnév használata

További nyelvek

Visszajelzés

További források

Megosztás a következőn keresztül:

Alkalmazások csatlakoztatása a Fabric API-hoz a GraphQL-hez

Előfeltételek

Microsoft Entra alkalmazás létrehozása

Minta GraphQL API beállítása alkalmazáshozzáféréshez

React-alkalmazás konfigurálása az ünnepnapok API-hoz való hozzáféréshez

Szolgáltatásnév használata

További nyelvek

Kapcsolódó tartalom

Visszajelzés

További források