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

Ha az alkalmazásokat a Fabric API-hoz csatlakoztatja a GraphQL-hez, a webes, mobil- és háttéralkalmazások modern, hatékony API-val kérdezik le a Fabric-adatforrásokat. Ehhez az integrációhoz a Microsoft Entra azonosítójával és az alkalmazás konfigurálásával megfelelő hitelesítésre van szükség a GraphQL-végpont biztonságos meghívásához.

Ez a cikk bemutatja egy React-alkalmazás és a Fabric GraphQL API csatlakoztatását a következő módon:

1. Microsoft Entra-alkalmazás létrehozása és konfigurálása hitelesítéshez
2. Minta GraphQL API beállítása a Fabricben lekérdezési adatokkal
3. Teljes React-alkalmazás klónozása és konfigurálása a GitHubról
4. A hitelesített kapcsolat tesztelése

Az oktatóanyag a Reactt használja, de a hitelesítési fogalmak bármilyen nyelvre érvényesek. C#-, Python- vagy más nyelvű mintákért tekintse meg a Microsoft Fabric Samples GitHub-adattárat.

Kinek kell alkalmazásokat csatlakoztatnia?

Az alkalmazáskapcsolat beállítása elengedhetetlen a következő célokhoz:

• Web- és mobilfejlesztők olyan alkalmazásokat fejlesztenek, amelyek adatokat használnak fel Fabric lakehouse-okból és raktárakból
• Integrációs fejlesztők, amelyek hálóadatokat csatlakoztatnak egyéni alkalmazásokhoz és automatizált munkafolyamatokhoz
• Háttérfejlesztők , amelyek olyan szolgáltatásokat hoznak létre, amelyek integrálhatók a Fabric egyesített elemzési platformjával
• Az adatmérnökök automatizált adatfeldolgozási munkafolyamatokat állíthatnak be, amelyek a Fabric-adatokat API-k használatával használják fel

Ezt az útmutatót akkor használja, ha hitelesítenie kell és engedélyeznie kell az alkalmazásokat a Fabric GraphQL API-k eléréséhez.

Előfeltételek

• Fejlesztői eszközök: A Node.js (LTS-verzió) és a Visual Studio Code-ra van szüksége a számítógépen.

• Mielőtt csatlakoztat egy alkalmazást, győződjön meg arról, hogy rendelkezik 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.

• A GraphQL API-hoz az alkalmazásoknak a Microsoft Entra-t kell használniuk a hitelesítéshez. Regisztrálja és konfigurálja az alkalmazást API-hívások végrehajtására a Fabricen. További információ: Microsoft Entra-alkalmazás létrehozása az Azure-ban.

• Az API-t meghívó hitelesített hitelesítő adatoknak (egyszerű felhasználónak, szolgáltatásnévnek vagy felügyelt identitásnak) végrehajtási engedélyekre van szüksége a GraphQL API-hoz (lekérdezések és mutációk futtatása közvetlen hozzáférési engedélyek hozzáadásakor). Ha egyszeri bejelentkezést (SSO) használ az API kapcsolati lehetőségeként, győződjön meg arról, hogy a hitelesítő adatok olvasási vagy írási engedélyekkel rendelkeznek a kiválasztott adatforrásban. További információ: Csatlakozás adatforráshoz és a sémalétrehozása.

Hitelesítés és engedélyek összegzése

A GraphQL API-hoz való hozzáféréshez az API és a mögöttes adatforrás szintjén is megfelelő hitelesítésre és engedélyezésre van szükség. Hitelesítéshez használhat felhasználónevet (egyéni felhasználót) vagy egy szolgáltatásnevet (amely egy alkalmazást vagy szolgáltatást jelöl). Az adatforrás-kapcsolathoz használhat egyszeri bejelentkezést (SSO ), ahol a hívó identitása átkerül az adatforrásba, vagy olyan mentett hitelesítő adatokat , ahol előre konfigurált kapcsolatot használ.

Az alábbi táblázat összefoglalja a különböző támogatott hitelesítési forgatókönyveket és a GraphQL API-t elérő ügyfelek minimálisan szükséges engedélyeit:

API-hívó	Adatforrás-kapcsolatok	Szükséges GraphQL API-engedélyek	Szükséges adatforrás-engedélyek	Microsoft Entra alkalmazás hatóköre
Egyszerű felhasználó (UPN)	Egyszeri bejelentkezés (SSO)	Lekérdezések és mutációk futtatása API-szinten	Az UPN-nek adott megfelelő olvasási/írási engedélyek az adatforrásban	GraphQLApi.Execute.All
Szolgáltatásnév (SPN)	Egyszeri bejelentkezés (SSO)	Lekérdezések és mutációk futtatása API-szinten	Az egyszerű szolgáltatásnévnek adott megfelelő olvasási/írási engedélyek az adatforrásban	Nem alkalmazható
Egyszerű felhasználó (UPN)	Mentett hitelesítő adatok	Lekérdezések és mutációk futtatása API-szinten	Az adatforrás mentett hitelesítő adatainak (kapcsolatának) megfelelő olvasási/írási engedélyek	GraphQLApi.Execute.All
Szolgáltatásnév (SPN)	Mentett hitelesítő adatok	Lekérdezések és mutációk futtatása API-szinten	Az egyszerű szolgáltatásnévnek adott megfelelő olvasási/írási engedélyek az adatforrásban	Nem alkalmazható

Microsoft Entra alkalmazás létrehozása

Mielőtt az alkalmazás meghívhatja a Fabric GraphQL API-t, regisztrálnia kell azt a Microsoft Entra-azonosítóban. Ez a regisztráció létrehoz egy identitást az alkalmazás számára, és meghatározza, hogy milyen engedélyekre van szüksége. A regisztrációs folyamat létrehoz egy ügyfél-azonosítót (alkalmazásazonosítót), és létrehozza azt a hitelesítési folyamatot, amelyet az alkalmazás a hozzáférési jogkivonatok beszerzéséhez használ.

A React-alkalmazások esetében egyoldalas alkalmazásbeállításokat (SPA) konfigurálhat, amelyek a PKCE-folyamatot használják – ez egy olyan biztonságos hitelesítési módszer, amelyet böngészőalapú alkalmazásokhoz terveztek, ahol az ügyfél titkos kulcsait nem lehet biztonságosan tárolni.

1. Alkalmazás regisztrálása az rövid útmutatóban leírt lépések használatával: Alkalmazás regisztrálása a Microsoft identitásplatformon.

2. A Microsoft Entra alkalmazás (ügyfél) azonosítója és címtár (bérlő) azonosítója az Összegzés dobozban jelenik meg. Jegyezze fel ezeket az értékeket, mert szüksége van rájuk a React-alkalmazás konfigurálásakor.

3. Konfigurálja az API-engedélyeket, hogy az alkalmazás hozzáférhessen a Fabric GraphQL API-hoz. A Kezelés listában válassza a API-engedélyeket, majd kattintson a Engedély hozzáadásagombra.

4. Adja hozzá a PowerBI szolgáltatást, válassza a Delegált engedélyek lehetőséget, majd a GraphQLApi.Execute.All engedélyeket. Ez az engedély lehetővé teszi, hogy az alkalmazás lekérdezéseket és mutációkat hajtson végre a bejelentkezett felhasználó nevében. Győződjön meg arról, hogy nincs szükség rendszergazdai hozzájárulásra.

5. Lépjen vissza a Kezelés listához, és válassza a Hitelesítés>egyoldalas alkalmazás> lehetőséget.

6. Helyi fejlesztési célokból 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 tapasztal, adja hozzá a Mobil és asztali alkalmazásplatformot az előző lépésben ugyanazzal az átirányítási URI-val.

7. Lépjen vissza a Hitelesítésszakaszhoz, görgessen le a Speciális beállítások részhez, majd a Nyilvános ügyfélfolyamatok engedélyezésealatt válassza az Igen lehetőséget a Az alábbi mobil- és asztali folyamatok engedélyezéseesetén.

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

Miután regisztrálta a Microsoft Entra alkalmazást, a lekérdezéshez egy GraphQL API-ra van szüksége a Fabricben. Ez a szakasz bemutatja, hogyan hozhat létre minta API-t a Fabric ünnepnapok adatkészletével. Ez egy működő API-t biztosít a hitelesítés és az adatlekérés teszteléséhez anélkül, hogy saját adatforrásokat kellene konfigurálnia.

A minta API egy Lakehouse-táblából tesz közzé ünnepnapadatokat, amelyeket a React-alkalmazás lekérdez a munkaszüneti napok megjelenítéséhez.

1. 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.

2. Az Adatmérnöki 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étrehozzon egy új Lakehouse-t, amely tartalmazza a munkaszüneti napok adatait.

   

3. Kövesse az API létrehozása a GraphQL-hez című cikk lépéseit egy új GraphQL API létrehozásához, é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.

   

4. A React-alkalmazás létrehozása előtt ellenőrizze, hogy az API megfelelően működik-e az API-szerkesztőben való teszteléssel. Használja a következő lekérdezést – ez ugyanaz a lekérdezés, amelyet a React-alkalmazás később hajt végre:

    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. Válassza a Végpont másolása lehetőséget az API-elem eszköztárán.

   

6. A Másolás hivatkozás képernyőn válassza a Másolás lehetőséget.

   

7. Jegyezze fel az ügyfél- és bérlőazonosítót a Microsoft Entra alkalmazásból és a végpont URI-jából. Ezekre az értékekre a React-alkalmazás konfigurálásakor van szükség.

A React-alkalmazás klónozása és konfigurálása

Most, hogy beállította a Microsoft Entra alkalmazást és a GraphQL API-t, konfigurálhat egy React-alkalmazást, hogy csatlakozzon hozzájuk. Az alkalmazás a Microsoft Authentication Library (MSAL) használatával kezeli a hitelesítést, és a GraphQL-kéréseket Bearer-jogkivonatokkal végzi.

1. Klónozza a mintaadattárat a GitHubról:

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

2. Nyissa meg a React alkalmazásmappát:

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

   A mappa egy teljes React-alkalmazást tartalmaz. Az adott végpont és hitelesítő adatok konfigurálásához csak a src/authConfig.js fájlt kell szerkesztenie.

3. Nyissa meg a projektet a kódszerkesztőben:

   code .
   

4. A szerkesztőben lépjen a src mappára, és nyissa meg a authConfig.js fájlt.

5. Cserélje le a következő helyőrző értékeket a megadott adatokra:

   • Enter_the_GraphQL_Endpoint_Here – Cserélje le a GraphQL API-végpontra egy minta GraphQL API beállításával az alkalmazáshoz való hozzáféréshez
   • Enter_the_Application_Id_Here– Cserélje le a alkalmazás (ügyfél) azonosítót a Microsoft Entra alkalmazás létrehozása alatt
   • Enter_the_Tenant_Info_Here– Cserélje ki a címtár (bérlő) azonosítóját az Microsoft Entra-alkalmazás létrehozásakor

   Fontos

   Ugyanabban a fájlban az loginRequest állandó tartalmazza a hatókört https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Ez a hatókör szükséges a Fabric GraphQL API-k eléréséhez. Ne távolítsa el vagy módosítsa ezt a hatókört; ellenkező esetben a hitelesítés meghiúsul.

6. Mentse a fájlt.

7. A terminálban keresse meg a projekt gyökérmappáját, és futtassa a következőt:

   npm install
   

   Ez telepíti az összes szükséges függőséget.

Az alkalmazás tesztelése

Ha az alkalmazás konfigurálva van, futtassa helyileg annak ellenőrzéséhez, hogy minden megfelelően működik-e:

1. A terminálban futtassa a következőt:

   npm start
   

   Ez a parancs elindítja a fejlesztői kiszolgálót, és megnyitja az alkalmazást a böngészőben.

2. Fejezze be a hitelesítési folyamatot, amikor az alkalmazás betöltődik.http://localhost:3000 Kövesse az oktatóanyagban leírt bejelentkezési lépéseket, és hívja meg az API-t az alkalmazásból.

3. A sikeres bejelentkezés után válassza a Query Fabric API for GraphQL Data gombot. Ez elindítja a hitelesítési folyamatot, beolvas egy hozzáférési jogkivonatot, és végrehajtja a GraphQL-lekérdezést a Fabric API-n.

   

4. Ha minden megfelelően van konfigurálva, az alkalmazás megjeleníti a munkaszüneti napokat egy táblázatban. Ez megerősíti, hogy:

   • A Microsoft Entra-alkalmazás rendelkezik a megfelelő engedélyekkel
   • A hozzáférési jogkivonat beszerzése sikeresen megtörtént
   • A GraphQL API hitelesítette a kérést
   • A Lakehouse-adatokon végrehajtott lekérdezés

   

Egyéb npm-parancsok

npm startEzeken kívül npm install ezeket a gyakori npm-parancsokat használhatja különböző fejlesztési forgatókönyvekhez:

• npm run dev – A fejlesztési kiszolgáló indításának alternatív módja
• npm run build – Az alkalmazás optimalizált éles buildjének létrehozása
• npm run preview – A build verzió helyi tesztelése az üzembe helyezés előtt
• npm test – Automatikus tesztek futtatása a kód helyes működésének ellenőrzéséhez

Kapcsolódó tartalom

Most, hogy egy működő alkalmazás csatlakozik a Fabric GraphQL API-hoz, fedezze fel ezeket az erőforrásokat kifinomultabb megoldások létrehozásához:

• API létrehozása a GraphQL-hez a Fabricben és adatok hozzáadása – Saját adatforrások közzététele
• Több adatforrás lekérdezése a Fabric API-ban a GraphQL-hez – Különböző forrásokból származó adatok egyesítése egyetlen lekérdezésben
• Fabric API a GraphQL-szerkesztőhöz – Lekérdezések interaktív tesztelése és fejlesztése
• Microsoft Entra alkalmazás létrehozása az Azure-ban – Részletes útmutató a termelési alkalmazás regisztrációjához
• Microsoft Fabric GraphQL-minták – Minták böngészése különböző nyelveken