Sdílet prostřednictvím

Připojení aplikací k rozhraní FABRIC API pro GraphQL

Propojení aplikací s rozhraním API Fabric pro GraphQL umožňuje webovým, mobilním a back-endovým aplikacím dotazovat zdroje dat Fabric pomocí moderního efektivního rozhraní API. Tato integrace vyžaduje správné ověřování prostřednictvím MICROSOFT Entra ID a konfigurace vaší aplikace pro bezpečné volání koncového bodu GraphQL.

Tento článek vás provede připojením aplikace React k rozhraní API GraphQL Fabric pomocí:

  1. Vytvoření a konfigurace aplikace Microsoft Entra pro ověřování
  2. Nastavení ukázkového rozhraní GraphQL API ve Fabricu s daty k dotazování
  3. Klonování a konfigurace kompletní aplikace React z GitHubu
  4. Testování ověřeného připojení

Tento kurz používá React, ale koncepty ověřování platí pro libovolný jazyk. Ukázky v C#, Pythonu nebo jiných jazycích najdete v úložišti GitHub s ukázkami Microsoft Fabric.

Kdo potřebuje připojit aplikace

Nastavení připojení k aplikaci je nezbytné pro:

  • Weboví a mobilní vývojáři vytvářející aplikace, které využívají data z Fabric lakehouse a datových skladů
  • Vývojáři integrace připojující data Fabric k vlastním aplikacím a automatizovaným pracovním postupům
  • Backendoví vývojáři vytvářející služby, které se integrují s jednotnou analytickou platformou Fabric
  • Datoví inženýři nastavují pracovní postupy automatizovaného zpracování dat, které využívají data Fabric prostřednictvím API.

Tuto příručku použijte, když potřebujete ověřovat a autorizovat aplikace pro přístup k rozhraním API GraphQL Fabric.

Požadavky

  • Vývojové nástroje: Na počítači potřebujete Node.js (verze LTS) a Visual Studio Code .

  • Před připojením aplikace se ujistěte, že máte API pro GraphQL ve Fabric. Další informace najdete v tématu Vytvoření rozhraní API pro GraphQL v prostředcích infrastruktury a přidání dat.

  • Rozhraní API pro GraphQL vyžaduje, aby aplikace k ověřování používaly Microsoft Entra. Zaregistrujte a nakonfigurujte aplikaci tak, aby prováděla volání rozhraní API pro Fabric. Další informace najdete v tématu Vytvoření aplikace Microsoft Entra v Azure.

  • Ověřené přihlašovací údaje (uživatelský účelový objekt, účelový objekt služby nebo spravovaná identita) volající rozhraní API potřebují oprávnění Execute pro rozhraní GraphQL API (volba Spustit dotazy a změny při přidávání přímých přístupových oprávnění). Pokud jako možnost připojení v rozhraní API používáte jednotné přihlašování, ujistěte se, že přihlašovací údaje mají ve zvoleném zdroji dat oprávnění ke čtení nebo zápisu. Další informace najdete v tématu Připojení ke zdroji dat a sestavení schématu.

Souhrn ověřování a oprávnění

Přístup k rozhraní GraphQL API vyžaduje správné ověřování a autorizaci na úrovni rozhraní API i na úrovni podkladového zdroje dat. Ověření můžete provést pomocí instančního objektu (představujícího jednotlivého uživatele) nebo instančního objektu (představujícího aplikaci nebo službu). Pro připojení ke zdroji dat můžete použít jednotné přihlašování ( SSO), ve kterém se identita volajícího předává zdroji dat, nebo uložené přihlašovací údaje , kde se používá předem nakonfigurované připojení.

Následující tabulka shrnuje různé podporované scénáře ověřování a minimální požadovaná oprávnění pro klienty, kteří přistupují k rozhraní GraphQL API:

Volající rozhraní API Připojení ke zdroji dat Požadovaná oprávnění rozhraní GraphQL API Požadovaná oprávnění ke zdroji dat Rozsah aplikace Microsoft Entra
Instanční objekt uživatele (UPN) Jednotné přihlašování (SSO) Spouštěnídotazůchch Příslušná oprávnění ke čtení a zápisu udělená hlavnímu názvu uživatele (UPN) ve zdroji dat GraphQLApi.Execute.All
Instanční objekt (SPN) Jednotné přihlašování (SSO) Spouštěnídotazůchch Příslušná oprávnění ke čtení a zápisu udělená hlavnímu názvu služby (SPN) ve zdroji dat Nevztahuje se
Instanční objekt uživatele (UPN) Uložené přihlašovací údaje Spouštěnídotazůchch Příslušná oprávnění ke čtení a zápisu udělená uloženým přihlašovacím údajům (připojení) ve zdroji dat GraphQLApi.Execute.All
Instanční objekt (SPN) Uložené přihlašovací údaje Spouštěnídotazůchch Příslušná oprávnění ke čtení a zápisu udělená hlavnímu názvu služby (SPN) ve zdroji dat Nevztahuje se

Vytvoření aplikace Microsoft Entra

Než bude vaše aplikace moct volat rozhraní API Fabric GraphQL, musíte ho zaregistrovat v Microsoft Entra ID. Tato registrace vytvoří identitu pro vaši aplikaci a definuje, jaká oprávnění potřebuje. Proces registrace vygeneruje ID klienta (identifikátor aplikace) a vytvoří tok ověřování, který vaše aplikace používá k získání přístupových tokenů.

U aplikací React nakonfigurujete nastavení jednostránkové aplikace (SPA), která používají tok PKCE – zabezpečenou metodu ověřování určenou pro aplikace založené na prohlížeči, kde se tajné kódy klientů nedají bezpečně ukládat.

  1. Registrace aplikace pomocí kroků popsaných v Rychlém startu: Registrace aplikace na platformě Microsoft Identity Platform.

  2. Hodnoty ID aplikace Microsoft Entra (klient) a ID adresáře (tenanta) se zobrazí v poli Souhrn. Poznamenejte si tyto hodnoty, protože je potřebujete při konfiguraci aplikace React.

  3. Nakonfigurujte oprávnění rozhraní API, aby vaše aplikace přistupovala k rozhraní API GraphQL Fabric. V seznamu Spravovat vyberte oprávnění rozhraní API, a pak Přidat oprávnění.

  4. Přidejte službu PowerBI, vyberte Delegovaná oprávnění a vyberte Oprávnění GraphQLApi.Execute.All . Toto oprávnění umožňuje vaší aplikaci spouštět dotazy a mutace jménem přihlášeného uživatele. Ověřte, že souhlas správce není povinný.

  5. Vraťte se do seznamu Spravovat a vyberte Ověřování>Přidat platformu>jednostránkovou aplikaci.

  6. Pro účely místního vývoje přidejte http://localhost:3000 do identifikátorů URI přesměrování a ověřte, že je aplikace povolená pro tok autorizačního kódu s ověřovacím klíčem pro exchange kódu (PKCE). Výběrem tlačítka Konfigurovat uložte provedené změny. Pokud aplikace narazí na chybu související s požadavky mezi různými zdroji, přidejte platformu mobilních a desktopových aplikací v předchozím kroku se stejnou URI adresou přesměrování.

  7. Zpět na Ověřování, sjeďte dolů na Rozšířené nastavení a v části Povolení veřejných klientských tokůzaškrtněte Ano u Povolit následující mobilní a desktopové toky.

Nastavení ukázkového rozhraní GraphQL API pro přístup k aplikacím

cs-CZ: Jakmile máte zaregistrovanou aplikaci Microsoft Entra, potřebujete GraphQL API v Fabric pro dotazy. Tato část vás provede vytvořením ukázkového rozhraní API pomocí datové sady veřejných svátků Fabric. Tím získáte funkční rozhraní API pro testování ověřování a načítání dat, aniž byste museli konfigurovat vlastní zdroje dat.

Ukázkové rozhraní API zveřejňuje data veřejných svátků z tabulky Lakehouse, na kterou se aplikace React dotazuje pro zobrazení těchto svátků.

  1. Na domovské stránce portálu Fabric vyberte Datoví technici ze seznamu úloh.

  2. V prostředí pro přípravu dat vyberte Použít ukázku a v části Lakehouse vyberte Státní svátky, aby se automaticky vytvořil nový Lakehouse s daty svátků.

    Snímek obrazovky s výběrem ukázkové možnosti Data Lakehouse

  3. Podle pokynů v tématu Vytvoření rozhraní API pro GraphQL vytvořte nové GraphQL rozhraní API a vyberte Lakehouse, který jste vytvořili. Přidejte tabulku svátků, aby klienti mohli k datům přistupovat.

    Snímek obrazovky s přidáním ukázkového Lakehouse jako zdroje dat GraphQL

  4. Před vytvořením aplikace React ověřte, že vaše rozhraní API funguje správně, a to tím, že ho otestujete v editoru rozhraní API. Použijte následující dotaz– jedná se o stejný dotaz, který aplikace React spustí později:

     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 panelu nástrojů položky rozhraní API vyberte Kopírovat koncový bod .

    Snímek obrazovky s možnostmi panelu nástrojů pro položku rozhraní API

  6. Na obrazovce Kopírovat odkaz vyberte Kopírovat.

    Snímek obrazovky dialogového okna Kopírovat odkaz, který ukazuje, kde vybrat Kopírovat.

  7. Zaznamená ID klienta a ID tenanta z aplikace Microsoft Entra a identifikátor URI koncového bodu. Tyto hodnoty potřebujete při konfiguraci aplikace React.

Klonování a konfigurace aplikace React

Teď, když máte aplikaci Microsoft Entra a rozhraní GraphQL API nastavené, můžete nakonfigurovat aplikaci React, aby se k nim připojila. Aplikace používá knihovnu MSAL (Microsoft Authentication Library) ke zpracování ověřování a vytváří požadavky GraphQL s nosnými tokeny.

  1. Naklonujte úložiště ukázek z GitHubu:

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

  2. Přejděte do složky aplikace React:

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

    Složka obsahuje úplnou aplikaci React. Ke konfiguraci konkrétního koncového bodu a přihlašovacích údajů stačí jenom upravit src/authConfig.js .

  3. Otevřete projekt v editoru kódu:

    code .

  4. V editoru src přejděte do složky a otevřete authConfig.js.

  5. Nahraďte následující zástupné hodnoty konkrétními podrobnostmi:

    Důležité

    Ve stejném souboru konstanta loginRequest obsahuje obor https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Tento konkrétní rozsah je vyžadován pro přístup k rozhraním API GraphQL Fabric. Neodebíjejte ani neupravujte tento obor; jinak ověřování selže.

  6. Uložte soubor.

  7. V terminálu přejděte do kořenové složky projektu a spusťte:

    npm install

    Tím se nainstalují všechny požadované závislosti.

Testování aplikace

Když je aplikace nakonfigurovaná, spusťte ji místně, abyste ověřili, že všechno funguje správně:

  1. V terminálu spusťte:

    npm start

    Tento příkaz spustí vývojový server a otevře aplikaci v prohlížeči.

  2. Dokončete tok ověřování, když se aplikace načte .http://localhost:3000 Postupujte podle kroků přihlášení popsaných v části Kurzu Volání rozhraní API z aplikace.

  3. Po úspěšném přihlášení vyberte tlačítko Query Fabric API pro data GraphQL . Tím se aktivuje tok ověřování, získá přístupový token a spustí dotaz GraphQL pro vaše rozhraní Fabric API.

    Snímek obrazovky ukázkové aplikace React po přihlášení

  4. Pokud je vše správně nakonfigurované, aplikace zobrazí v tabulce státní svátky. To potvrzuje, že:

    • Vaše aplikace Microsoft Entra má správná oprávnění.
    • Přístupový token byl úspěšně získán.
    • Rozhraní GraphQL API ověřilo požadavek.
    • Dotaz se spustil proti datům Lakehouse.

    Snímek obrazovky ukázkové aplikace React po přijetí požadavku GraphQL

Další příkazy npm

Kromě npm start a npm install můžete použít tyto obvyklé příkazy npm pro různé vývojové scénáře:

  • npm run dev - Alternativní způsob spuštění vývojového serveru
  • npm run build – Vytvoření optimalizovaného produkčního sestavení vaší aplikace
  • npm run preview – Testování produkčního sestavení místně před nasazením
  • npm test – Spuštěním automatizovaných testů ověřte, že váš kód funguje správně.

Související obsah

Teď, když máte funkční aplikaci připojenou k rozhraní API GraphQL Fabric, prozkoumejte tyto prostředky a sestavte sofistikovanější řešení:

  • Last updated on