Pripojenie aplikácií k databáze API služby Fabric pre GraphQL

Ak chcete pripojiť aplikáciu k rozhraniu API pre GraphQL, potrebujete tri dôležité informácie: ID klienta, ID nájomníka a adresu koncového bodu GraphQL v službe Fabric. V nasledujúcich častiach vám predstavíme, ako vytvoriť a načítať všetky potrebné podrobnosti a ako získať prístup k rozhraniu API pomocou ukážkovej aplikácie.

• Rozhranie API pre GraphQL v súčasnosti vyžaduje, aby aplikácie používali na overovanie microsoft Entra. Vaša aplikácia musí byť zaregistrovaná a primerane nakonfigurovaná na vykonávanie volaní API v službe Fabric. Ďalšie informácie nájdete v téme Vytvorenie aplikácie Microsoft Entra v službe Azure.

• Overený používateľ volajúci rozhranie API vyžaduje povolenia Execute k rozhraniu GraphQL API (možnosť Spustiť dotazy a mutácie pri pridávaní priamych povolení na prístup). Ak sa ako možnosť pripojenia v rozhraní API používa jediné prihlásenie (SSO), v zdroji údajov podľa toho sa vyžadujú povolenia na čítanie alebo zapisovanie. Ďalšie informácie nájdete Pripojenie k zdroju údajov a vytvorenie schémy.

• Pred pripojením aplikácie musíte mať rozhranie API pre GraphQL v službe Fabric. Ďalšie informácie nájdete v téme Vytvorenie rozhrania API pre GraphQL v službe Fabric a pridanie údajov.

V nasledujúcich krokoch si predstavíme, ako nakonfigurovať podporu pre aplikáciu ReactJS v microsoft Entre.

1. Registrácia aplikácie pomocou krokov opísaných v téme Stručný návod: Registrácia aplikácie pomocou platformy identity spoločnosti Microsoft.
2. Vaše hodnoty ID aplikácie Microsoft Entra (klient) a ID adresára (nájomníka) sa zobrazujú v poli Súhrn. Zaznamenávajte tieto hodnoty tak, ako sa vyžadujú neskôr.
3. V zozname Spravovať vyberte povolenia rozhrania APIa potom Pridať povolenie.
4. Pridajte službyPowerBI , vyberte delegované povoleniaa potom vyberte povolenia GraphQL.Execute.All. Skontrolujte, či sa nevyžaduje súhlas správcu.
5. Vráťte sa do zoznamu Spravovať a vyberte položku , >
6. Na lokálne účely vývoja pridajte do http://localhost:3000 časti Identifikátory URI presmerovania a potvrďte, že je aplikácia povolená pre postup kódu oprávnenia s overeným kľúčom pre Exchange kódov (PKCE). Ak chcete zmeny uložiť, vyberte tlačidlo Konfigurovať. V prípade, že aplikácia dostane chybu súvisiacu so žiadosťami krížového pôvodu, pridajte v predchádzajúcom kroku platformu mobilných a počítačových aplikácií s rovnakým identifikátorom URI presmerovania.
7. Späť na overovania , prejdite nadol na rozšírené nastavenia a v časti Povoliťverejné klientske postupy vyberte položku Áno pre Povoliť nasledujúce mobilné postupy a postupy pracovnej plochy.

V tomto príklade vytvoríme rozhranie API GraphQL, ktoré bude klientom sprístupniť vzorové údaje lakehouse.

1. Na domovskej stránke portálu služby Fabric vyberte v zozname vyťažení položku Dátový inžinier ing (vyťaženia).

2. V Dátový inžinier prostredí vyberte položku Použiť ukážku a v časti Lakehouse vyberte položku Štátne sviatky a automaticky vytvorte nový lakehouse s údajmi o sviatkoch.

   

3. Podľa krokov z návodu Vytvorenie rozhrania API pre GraphQL vytvorte nové rozhranie GraphQL API a vyberte súbor Lakehouse, ktorý ste vytvorili. Pridajte tabuľku štátne sviatky, aby klienti mohli pristupovať k týmto údajom.

   

4. Testovanie rozhrania GraphQL API v editore rozhrania API pomocou nasledujúceho vzorového dotazu. Ide o rovnaký dotaz, ktorý používame v klientskej aplikácii React:

    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. Na paneli s nástrojmi položky rozhrania API vyberte položku Kopírovať koncový bod .

   

6. Na obrazovke Kopírovať prepojenie vyberte položku Kopírovať.

   

7. Keďže ID klienta a ID nájomníka z aplikácie Microsoft Entra boli zaznamenané skôr, skopírujte identifikátor URI koncového bodu tak, ako sa vyžaduje neskôr.

1. Ako východiskový bod použijeme existujúcu aplikáciu React. Postupujte podľa všetkých krokov v kurze : Vytvorte jednostranovú aplikáciu React a pripravte ju na overovanie na vytvorenie projektu knižnice React s nakonfigurovaným overovaním microsoft Entra vrátane ďalších súborov a priečinkov potrebných na pridanie do štruktúry projektu. Potrebujeme len zmeniť tri súbory na prispôsobenie aplikácie pre náš prípad použitia v jazyku GraphQL.

2. V priečinku src otvorte súbor authConfig.js a nahraďte obsah súboru nasledujúcim úryvkom kódu:

    /*
     * 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/GraphQL.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",
    };
   

   Ako môžete vidieť v kóde uvedenom vyššie, je dôležité použiť správny rozsah na prístup k aplikácii. V našom prípade https://analysis.windows.net/powerbi/api/GraphQL.Execute.All...

3. Nahraďte nasledujúce hodnoty hodnotami z Centra spravovania služby Microsoft Entra.

   • clientId - Identifikátor aplikácie, tiež označované ako klient. Nahraďte Enter_the_Application_Id_Here hodnotou ID aplikácie (klienta), ktorá bola zaznamenaná skôr zo stránky s prehľadom registrovanej aplikácie Microsoft Entra.
   • authority – Skladá sa z dvoch častí:
     • Inštancia je koncový bod poskytovateľa cloudu. Informujte sa o rôznych dostupných koncových bodoch v národných cloudoch.
     • ID nájomníka je identifikátor nájomníka, v ktorom je aplikácia zaregistrovaná. Nahraďte Enter_the_Tenant_Info_Here hodnotou ID adresára (nájomníka), ktorá bola zaznamenaná skôr zo stránky prehľadu zaregistrovanej aplikácie.
   • graphQLEndpoint – Rozhranie API služby Fabric pre koncový bod GraphQL. Nahraďte Enter_the_GraphQL_Endpoint_Here koncovým bodom rozhrania GraphQL API zaznamenaným skôr.

4. Uložte súbor.

5. V tom istom priečinku src otvorte súbor App.js a nahraďte obsah súboru nasledujúcim úryvkom kódu:

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

6. Uložte súbor.

7. Nakoniec v priečinku src/components otvorte súbor ProfileData.jsx a nahraďte obsah súboru nasledujúcim úryvkom kódu:

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

8. Uložte všetky zmeny súboru.

9. Vo svojej terminálovej aplikácii podľa výberu prejdite do koreňového priečinka projektu React a vykonajte príkaz npm start na lokálne otestovanie aplikácie.

10. Akonáhle sa aplikácia načíta v prehliadači z http://localhost:3000, postupujte podľa krokov v poslednej časti kurzu Zavolať rozhranie API z aplikácie na overenie.

11. Po prihlásení kliknite na tlačidlo Rozhranie API služby Query Fabric pre údaje GraphQL.

    

12. Úspešná overovaná žiadosť do rozhrania GraphQL API v službe Fabric vráti údaje z dotazu GraphQL do služby Lakehouse v našej klientskej aplikácii React:

    

Hoci kroky v predchádzajúcej časti vyžadujú poskytnutie prístupu k objektom používateľa, prístup k rozhraniu GraphQL API môžete získať aj pomocou objektu služby:

1. Podľa krokov v predchádzajúcej časti vytvorte druhú aplikáciu Microsoft Entra s podobnými povoleniami (GraphQL.Execute.All rozsahu pre služby PowerBI ). V novej aplikácii pridajte tajný kľúč klienta v časti Certifikáty a tajné kódy, ďalšie informácie nájdete v téme Registrácia aplikácie Microsoft Entra a vytvorenie objektu služby.

2. Uistite sa, že správcovia nájomníkov povolili používanie objektov služby v službe Fabric. Na portáli na správu nájomníka prejdite do časti Nastavenia nájomníka. V časti Nastavenia pre vývojára povoľte, aby objekty služby mohli používať rozhrania API služby Fabric. Keď je toto nastavenie povolené, aplikácia bude na portáli služby Fabric viditeľná z dôvodu priradenia roly alebo povolení. Ďalšie informácie nájdete v podpore identity.

3. Objekt služby bude potrebovať prístup k rozhraniu GraphQL API aj zdroju údajov, presnejšie k povolenia Vykonať pre rozhranie API GraphQL a vyžaduje sa tiež prístup na čítanie alebo zapisovanie v zdroji údajov, ktorý si zvolíte. Na portáli služby Fabric otvorte pracovný priestor a vyberte tri bodky vedľa rozhrania API. Vyberte položku Spravovať povolenia pre rozhranie API a potom položku Pridať používateľa. Pridajte aplikáciu a vyberte položku Run Queries and Mutácie, ktorá poskytne požadované povolenia Execute (Vykonanie) pre objekt služby. Najjednoduchším spôsobom implementácie požadovaných povolení pre rozhranie API aj zdroj údajov je na testovacie účely pridanie aplikácie ako člena pracovného priestoru s rolou prispievateľa, v ktorej sa nachádza rozhranie API GraphQL aj položky zdroja údajov.

   

Keďže objekt služby vyžaduje certifikát alebo tajný kľúč klienta, nie je podporovaný knižnicou overenia spoločnosti Microsoft (MSAL) v jednostranových aplikáciách (SPA), ako je napríklad aplikácia React, ktorú sme vytvorili v poslednom kroku. V závislosti od požiadaviek a prípadov použitia môžete využívať serverovú službu, ktorá je správne zabezpečená pomocou presne definovanej logiky oprávnenia.

Po nakonfigurovaní rozhrania API na prístup k objektu služby ho môžete otestovať lokálne pomocou jednoduchej aplikácie Node.JS v lokálnom počítači:

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

Po inštalácii závislostí (@azure/identity) so správcom balíka služby Node.JS podľa vlastného výberu, úpravou súboru s požadovanými informáciami, uložením a spustením (node <filename.js>) budete môcť načítať token zo spoločnosti Microsoft Entra.

Token možno potom použiť na vyvolanie vášho rozhrania API GraphQL pomocou prostredia PowerShell nahradením príslušných podrobností za token , ktorý ste práve načítali, dotaz GraphQL, ktorý chcete spustiť, a koncového bodu rozhrania GraphQL API:

$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 

Prípadne môžete použiť hodnotu cURL na dosiahnutie rovnakého výsledku:

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

Na lokálne testovacie účely možno kód Node.JS mierne upraviť s dodatočnou závislosťou (axios) na načítanie tokenu a vyvolať rozhranie API v jednom spustení:

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

Vyhľadajte ukážky jazyka C#, Python a ďalších jazykov na pripojenie k vášmu prepojeniu s rozhraním GraphQL API v odkladacom priestore služby Microsoft Fabric Samples GitHub.

• Vytvorenie aplikácie Microsoft Entra v službe Azure
• Vytvorenie rozhrania API pre GraphQL v službe Fabric a pridanie údajov
• Vytvorenie jednostranovej aplikácie React a jej príprava na overenie
• Dotazovanie viacerých zdrojov údajov v rozhraní API služby Fabric pre GraphQL