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

Prepojenie aplikácií s Fabric API pre GraphQL umožňuje vašim webovým, mobilným a backendovým aplikáciám dotazovať sa na zdroje dát Fabric pomocou moderného, efektívneho API. Táto integrácia vyžaduje správnu autentifikáciu cez Microsoft Entra ID a konfiguráciu vašej aplikácie na bezpečné volanie koncového bodu GraphQL.

Tento článok vás prevedie prepojením React aplikácie s Fabric GraphQL API takto:

1. Vytvorenie a konfigurácia aplikácie Microsoft Entra na autentifikáciu
2. Nastavenie vzorového GraphQL API v Fabric s dátami na dotazovanie
3. Klonovanie a konfigurácia kompletnej React aplikácie z GitHubu
4. Testovanie autentifikovaného spojenia

Tutoriál používa React, ale autentifikačné koncepty platia pre akýkoľvek jazyk. Pre ukážky v C#, Python alebo iných jazykoch pozri Fabric Samples GitHub repozitár.

Kto potrebuje prepojiť aplikácie

Nastavenie pripojenia aplikácie je nevyhnutné pre:

• Weboví a mobilní vývojári vytvárajú aplikácie, ktoré spotrebovávajú dáta z Fabric lakehouse a skladov
• Vývojári integrácie spájajúci Fabric dáta s vlastnými aplikáciami a automatizovanými pracovnými tokami
• Backendoví vývojári vytvárajú služby integrované s jednotnou analytickou platformou Fabric
• Dátoví inžinieri nastavujú automatizované pracovné postupy spracovania dát, ktoré spotrebovávajú Fabric dáta prostredníctvom API

Použite tento návod, keď potrebujete autentifikovať a autorizovať aplikácie na prístup k vašim Fabric GraphQL API.

Požiadavky

• Vývojové nástroje: Potrebujete mať nainštalovanýNode.js (LTS verzia) a Visual Studio Code na vašom počítači.

• Pred pripojením aplikácie sa uistite, že máte rozhranie API pre GraphQL v štruktúre. Ďalšie informácie nájdete v téme Vytvorenie rozhrania API pre GraphQL v službe Fabric a pridanie údajov.

• Rozhranie API pre GraphQL vyžaduje, aby aplikácie používali na overovanie Microsoft Entra. Zaregistrujte a nakonfigurujte svoju aplikáciu na vykonávanie volaní rozhrania API v službe Fabric. Ďalšie informácie nájdete v téme Vytvorenie aplikácie Microsoft Entra v službe Azure.

• Overené poverenia (objekt používateľa, objekt služby alebo spravovaná identita), ktoré volajú rozhranie API, potrebujú povolenia na spustenie pre rozhranie API GraphQL (možnosť Spustiť dotazy a mutácie pri pridávaní povolení na priamy prístup). Ak používate jediné prihlásenie (SSO) ako možnosť pripojenia v rozhraní API, uistite sa, že poverenia majú povolenia na čítanie alebo zápis vo vybratom zdroji údajov. Ďalšie informácie nájdete Pripojenie k zdroju údajov a vytvorenie schémy.

Súhrn autentifikácie a povolení

Prístup k GraphQL API vyžaduje správnu autentifikáciu a autorizáciu na úrovni API aj na úrovni základného zdroja dát. Autentifikovať sa môžete buď pomocou používateľského princípu (reprezentujúceho jednotlivého používateľa) alebo servisného princípu (reprezentujúceho aplikáciu alebo službu). Pre pripojenie k dátovému zdroju môžete použiť jednotné prihlásenie (SSO), kde sa identita volajúceho odovzdáva zdroju dát, alebo uložené prihlasovacie údaje , kde sa používa predkonfigurované pripojenie.

Nasledujúca tabuľka zhrňuje rôzne podporované autentifikačné scenáre a minimálne požadované oprávnenia pre klientov pristupujúcich k GraphQL API:

Volajúci rozhrania API	Pripojiteľnosť zdroja údajov	Požadované povolenia rozhrania GraphQL API	Požadované povolenia zdroja údajov	Microsoft Entra app scope
Hlavné meno používateľa (UPN)	Jediné prihlásenie (SSO)	Spustenie dotazov a mutácií na úrovni rozhrania API	Príslušné povolenia na čítanie a zápis udelené hlavnému názvu používateľa v zdroji údajov	GraphQLApi.Execute.All
Objekt služby (SPN)	Jediné prihlásenie (SSO)	Spustenie dotazov a mutácií na úrovni rozhrania API	Príslušné povolenia na čítanie a zápis udelené hlavnému názvu služby v zdroji údajov.	Nevzťahuje sa
Hlavné meno používateľa (UPN)	Uložené poverenia	Spustenie dotazov a mutácií na úrovni rozhrania API	Príslušné povolenia na čítanie a zápis udelené uloženému prihlasovaciemu údaju (pripojenie) v zdroji údajov.	GraphQLApi.Execute.All
Objekt služby (SPN)	Uložené poverenia	Spustenie dotazov a mutácií na úrovni rozhrania API	Príslušné povolenia na čítanie a zápis udelené hlavnému názvu služby v zdroji údajov.	Nevzťahuje sa

Vytvorenie aplikácie Microsoft Entra

Predtým, než vaša aplikácia môže volať Fabric GraphQL API, musíte ju zaregistrovať v Microsoft Entra ID. Táto registrácia vytvára identitu pre vašu aplikáciu a určuje, aké oprávnenia potrebuje. Proces registrácie generuje ID klienta (identifikátor aplikácie) a stanovuje autentifikačný proces, ktorý vaša aplikácia používa na získanie prístupových tokenov.

Pre React aplikácie konfigurujete nastavenia jednostránkových aplikácií (SPA), ktoré používajú PKCE flow – bezpečnú autentifikáciu navrhnutú pre prehliadačové aplikácie, kde nie je možné bezpečne uložiť klientské tajomstvá.

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. Hodnoty ID aplikácie (klienta) aplikácie Microsoft Entra a ID adresára (nájomníka) sa zobrazia v poli Súhrn. Zaznamenávajte tieto hodnoty, pretože ich potrebujete pri konfigurácii aplikácie React.

3. Nastavte oprávnenia API, aby vaša aplikácia mohla pristupovať k Fabric GraphQL API. V zozname Spravovať vyberte povolenia rozhrania APIa potom Pridať povolenie.

4. Pridajte službu Power BI, vyberte Delegované oprávnenia a vyberte GraphQLApi.Execute.All permissions. Toto povolenie umožňuje vašej aplikácii vykonávať dotazy a mutácie v mene prihláseného používateľa. Skontrolujte, či sa nevyžaduje súhlas správcu.

5. Vráťte sa do zoznamu Spravovať a vyberte položku Overenie>Pridajte platformu>Jednostránková aplikácia.

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ť. Ak aplikácia narazí na chybu súvisiacu s požiadavkami medzi zdrojmi, pridajte platformu mobilných a desktopových aplikácií v predchádzajúcom kroku 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.

Nastavenie vzorového rozhrania GraphQL API na prístup k aplikácii

Ak máte zaregistrovanú Microsoft Entra aplikáciu, potrebujete GraphQL API vo Fabric na dotazovanie. Táto sekcia vás prevedie vytvorením vzorového API pomocou dátovej sady štátnych sviatkov od Fabric. Tým získate funkčné API na testovanie autentifikácie a získavania dát bez potreby konfigurácie vlastných zdrojov dát.

Ukážkové API zverejňuje sviatočné dáta z tabuľky lakehouse, ktoré vaša React aplikácia dotazuje na zobrazenie štátnych sviatkov.

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 prostredí dátového inžinierstva vyberte položku Použiť ukážku a v časti Lakehouse vyberte položku Štátne sviatky , aby sa automaticky vytvoril nový Lakehouse s údajmi o štátnych sviatkoch.

   

3. Postupujte podľa krokov v časti Vytvorenie rozhrania API pre GraphQL , vytvorte nové rozhranie GraphQL API a vyberte Lakehouse, ktorý ste vytvorili. Pridajte tabuľku štátnych sviatkov, aby klienti mali prístup k týmto údajom.

   

4. Pred vytvorením React aplikácie overte, či vaše API funguje správne, testovaním v API editore. Použite nasledujúci dotaz – je to ten istý dotaz, ktorý vaša React aplikácia vykoná neskôr:

    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. Zaznamenávajte ID klienta a Tenant ID z aplikácie Microsoft Entra a URL endpointu. Tieto hodnoty potrebujete pri konfigurácii aplikácie React.

Klonujte a konfigurujte aplikáciu React

Teraz, keď máte nastavenú aplikáciu Microsoft Entra a GraphQL API, môžete nastaviť aplikáciu React, aby sa k nim pripojila. Aplikácia používa Microsoft Authentication Library (MSAL) na spracovanie autentifikácie a vykonáva GraphQL požiadavky pomocou Bearer tokenov.

1. Klonujte úložisko ukážok z GitHubu:

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

2. Prejdite do priečinka aplikácie React:

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

   Priečinok obsahuje kompletnú aplikáciu React. Stačí upraviť src/authConfig.js len na konfiguráciu vášho konkrétneho endpointu a prihlasovacích údajov.

3. Otvorte projekt vo svojom editore kódu:

   code .
   

4. V editore prejdite do priečinka src a otvorte authConfig.js.

5. Nahraďte nasledujúce zástupné hodnoty svojimi konkrétnymi údajmi:

   • Enter_the_GraphQL_Endpoint_Here - Nahradiť vaším GraphQL API endpointom z Nastavte ukážkové GraphQL API pre prístup k aplikáciám
   • Enter_the_Application_Id_Here - Nahradiť vaším ID aplikácie (klienta) z Create a Microsoft Entra app
   • Enter_the_Tenant_Info_Here - Nahradiť svojím adresárom (tenant) ID z aplikácie Create a Microsoft Entra

   Important

   V tom istom súbore konštanta loginRequest zahŕňa rozsah https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Tento presný rozsah je potrebný na prístup k Fabric GraphQL API. Neodstraňujte ani neupravujte tento puškohľad; inak autentifikácia zlyhá.

6. Uložte súbor.

7. Vo vašom termináli prejdite do koreňového priečinka projektu a spustite:

   npm install
   

   Týmto sa nainštalujú všetky potrebné závislosti.

Otestujte aplikáciu

Keď je aplikácia nakonfigurovaná, spustite ju lokálne, aby ste overili, že všetko funguje správne:

1. Vo vašom termináli spustite:

   npm start
   

   Tento príkaz spustí vývojový server a otvorí aplikáciu vo vašom prehliadači.

2. Dokončite autentifikačný proces, keď sa aplikácia načíta na .http://localhost:3000 Postupujte podľa krokov prihlásenia popísaných v sekcii tutoriálov : Zavolajte API priamo z aplikácie.

3. Po úspešnom prihlásení vyberte tlačidlo Query Fabric API pre GraphQL Data . Tým sa spustí autentifikačný tok, získa prístupový token a vykoná sa dotaz GraphQL proti vášmu Fabric API.

   

4. Ak je všetko správne nastavené, aplikácia zobrazuje štátne sviatky v tabuľke. To potvrdzuje, že:

   • Vaša aplikácia Microsoft Entra má správne oprávnenia
   • Prístupový token bol úspešne získaný
   • GraphQL API overilo požiadavku
   • Dotaz vykonaný na dátach lakehouse

   

Ďalšie príkazy npm

Beyond npm start a , npm installmôžete použiť tieto bežné npm príkazy pre rôzne vývojové scenáre:

• npm run dev - Alternatívny spôsob spustenia vývojového servera
• npm run build - Vytvoriť optimalizovanú produkčnú verziu vašej aplikácie
• npm run preview - Otestovať produkčnú verziu lokálne pred nasadením
• npm test - Spúšťajte automatizované testy na overenie, že váš kód funguje správne

Súvisiaci obsah

Teraz, keď máte funkčnú aplikáciu pripojenú k vášmu Fabric GraphQL API, preskúmajte tieto zdroje na vytvorenie sofistikovanejších riešení:

• Vytvorte API pre GraphQL v Fabric a pridajte dáta – Naučte sa, ako sprístupniť vlastné zdroje dát
• Dotaz na viaceré dátové zdroje v Fabric API pre GraphQL – Spojte dáta z rôznych zdrojov do jedného dotazu
• Fabric API pre GraphQL editor – Testujte a vyvíjajte dotazy interaktívne
• Vytvoriť Microsoft Entra aplikáciu v Azure – Podrobný návod na registráciu produkčných aplikácií
• Fabric GraphQL ukážky - Prehliadajte ukážky vo viacerých jazykoch