Sovellusten yhdistäminen GraphQL:n Fabric-ohjelmointirajapintaan

Sovellusten yhdistäminen Fabricin API:iin GraphQL:lle mahdollistaa web-, mobiili- ja taustasovellusten kyselyt Fabricin tietolähteistä modernin ja tehokkaan API:n avulla. Tämä integraatio vaatii asianmukaisen todennuksen Microsoft Entra ID:n kautta ja sovelluksen konfiguroinnin GraphQL-päätepisteen turvalliseen kutsumiseen.

Tämä artikkeli opastaa sinua yhdistämään React-sovelluksen Fabric GraphQL API:hin seuraavasti:

1. Microsoft Entra -sovelluksen luominen ja konfigurointi autentikointia varten
2. GraphQL-rajapinnan näytteen perustaminen Fabricissa, jossa on dataa kyselyä varten
3. Täydellisen React-sovelluksen kloonaaminen ja konfigurointi GitHubista
4. Todennuksen yhteyden testaus

Opetusohjelmassa käytetään Reactia, mutta todennuskäsitteet pätevät mihin tahansa kieleen. C#:n, Pythonin tai muiden kielten näytteitä löydät Microsoft Fabric Samples GitHub -repositoriosta.

Kuka tarvitsee yhdistää sovelluksia

Sovelluksen yhteyden perustaminen on välttämätön:

• Verkko- ja mobiilikehittäjät rakentavat sovelluksia, jotka kuluttavat dataa Fabric-järven taloista ja varastoista
• Integraatiokehittäjät , jotka yhdistävät Fabric-datan räätälöityihin sovelluksiin ja automatisoituihin työnkulkuihin
• Backend-kehittäjät luovat palveluita, jotka integroituvat Fabricin yhtenäiseen analytiikkaalustaan
• Data-insinöörit perustavat automatisoituja tietojenkäsittelytyönkulkuja, jotka kuluttavat Fabric-dataa API:n kautta

Käytä tätä opasta, kun sinun täytyy todentaa ja valtuuttaa sovelluksia Fabric GraphQL -rajapintojen käyttöön.

Edellytykset

• Kehitystyökalut: Tarvitset Node.js (LTS-versio) ja Visual Studio Code asennettuna koneellesi.

• Varmista ennen sovelluksen yhdistämistä, että sinulla on GraphQL:n ohjelmointirajapinta Fabricissa. Lisätietoja on artikkelissa Ohjelmointirajapinnan luominen GraphQL:lle Fabricissa ja tietojen lisääminen.

• GraphQL:n ohjelmointirajapinta edellyttää, että sovellukset käyttävät Microsoft Entraa todentamiseen. Rekisteröi ja määritä sovelluksesi suorittamaan ohjelmointirajapintakutsuja Fabricia vastaan. Lisätietoja on artikkelissa Microsoft Entra -sovelluksen luominen Azuressa.

• Ohjelmointirajapintaa kutsuva todennettu tunnistetieto (käyttäjän päänimi, palvelun päänimi tai hallittu käyttäjätieto) tarvitsee GraphQL-ohjelmointirajapinnan suoritusoikeudet (Suorita kyselyt ja mutaatiot -vaihtoehto, kun lisäät suoran käytön käyttöoikeuksia). Jos käytät kertakirjautumista (SSO) ohjelmointirajapinnan yhteysvaihtoehtona, varmista, että tunnistetiedoilla on luku- tai kirjoitusoikeudet valitussa tietolähteessä. Lisätietoja on kohdassa Yhdistä tietolähteeseen ja luo rakenne.

Todennus- ja käyttöoikeuksien yhteenveto

GraphQL API:n käyttö vaatii asianmukaisen todennuksen ja valtuutuksen sekä API-tasolla että taustalla olevalla tietolähdetasolla. Voit todentaa joko käyttäjäpäähenkilöllä (edustaa yksittäistä käyttäjää) tai palvelupäähenkilöllä (joka edustaa sovellusta tai palvelua). Tietolähteiden yhdistämiseen voi käyttää kertakirjautumista (SSO ), jossa soittajan henkilöllisyys välitetään tietolähteelle, tai tallennettuja tunnuksia , joissa käytetään ennalta määritettyä yhteyttä.

Seuraava taulukko tiivistää eri tuetut todennusskenaariot ja vähimmäisvaatimukset GraphQL API:n käyttäjille:

Ohjelmointirajapinnan soittaja	Tietolähteen liitettävyys	Vaaditut GraphQL-ohjelmointirajapinnan käyttöoikeudet	Vaaditut tietolähteen käyttöoikeudet	Microsoft Entra app scope
Käyttäjän pääkäyttäjä (UPN)	Kertakirjautuminen (SSO)	Suorita kyselyjä ja mutaatioita ohjelmointirajapinnan tasolla	Asianmukaiset luku- ja kirjoitusoikeudet, jotka on myönnetty upn:lle tietolähteessä	GraphQLApi.Execute.All
Palvelun päänimi (SPN)	Kertakirjautuminen (SSO)	Suorita kyselyjä ja mutaatioita ohjelmointirajapinnan tasolla	Palvelun päänimelle tietolähteessä myönnetyt tarvittavat luku- ja kirjoitusoikeudet	Ei käytettävissä
Käyttäjän pääkäyttäjä (UPN)	Tallennetut tunnistetiedot	Suorita kyselyjä ja mutaatioita ohjelmointirajapinnan tasolla	Tallennetulle tunnistetiedot (yhteydelle) on myönnetty asianmukaiset luku- ja kirjoitusoikeudet tietolähteessä	GraphQLApi.Execute.All
Palvelun päänimi (SPN)	Tallennetut tunnistetiedot	Suorita kyselyjä ja mutaatioita ohjelmointirajapinnan tasolla	Palvelun päänimelle tietolähteessä myönnetyt tarvittavat luku- ja kirjoitusoikeudet	Ei käytettävissä

Luo Microsoft Entra -sovellus

Ennen kuin sovelluksesi voi kutsua Fabric GraphQL API:n, sinun täytyy rekisteröidä se Microsoft Entra ID:hen. Tämä rekisteröinti luo sovelluksellesi identiteetin ja määrittelee, mitä oikeuksia se tarvitsee. Rekisteröintiprosessi luo Client ID:n (sovellustunnisteen) ja määrittää todennuskulun, jota sovelluksesi käyttää käyttöoikeustokenien hankkimiseen.

React-sovelluksissa konfiguroidaan yksittäisen sivun sovellusasetukset (SPA), jotka käyttävät PKCE-flow'ta—turvallista todennusmenetelmää, joka on suunniteltu selainpohjaisille sovelluksille, joissa asiakassalaisuuksia ei voi turvallisesti tallentaa.

1. Rekisteröi sovellus noudattamalla ohjeita kohdassa Pikaopas: Sovelluksen rekisteröinti Microsoftin käyttäjätietoympäristössä.

2. Microsoft Entra -sovelluksen sovelluksen (asiakasohjelman) tunnuksen ja hakemiston (vuokraajan) tunnuksen arvot näkyvät Yhteenveto-ruudussa. Tallenna nämä arvot, koska tarvitset niitä React-sovelluksen konfiguroinnin yhteydessä.

3. Määritä API-oikeudet niin, että sovelluksesi pääsee käsiksi Fabric GraphQL API:iin. Valitse Hallinta -luettelosta -ohjelmointirajapinnan käyttöoikeudetja valitse sitten Lisää käyttöoikeus -.

4. Lisää PowerBI-palvelu, valitse Delegoidut käyttöoikeudet ja valitse GraphQLApi.Execute.All permissions. Tämä oikeus sallii sovelluksesi suorittaa kyselyitä ja muutoksia kirjautuneen käyttäjän puolesta. Varmista, että järjestelmänvalvojan suostumusta ei tarvita.

5. Palaa Hallinta-luetteloon ja valitse Todennus>Lisää alustan>yksisivuinen sovellus.

6. Lisää paikallisiin kehitystarkoituksiin kohtaan http://localhost:3000Uudelleenohjauksen URI-osoitteet ja varmista, että sovellus on otettu käyttöön valtuutuskoodin työnkulussa, jossa on Koodin vaihto -ohjelman (PKCE) todisteavain. Tallenna muutoksesi valitsemalla Määritä-painike. Jos sovellus kohtaa virheen, joka liittyy alkuperän välisiin pyyntöihin, lisää mobiili- ja työpöytäsovellusympäristö edellisessä vaiheessa samalla uudelleenohjaus-URI:lla.

7. Siirry Authentication-alaspäin kohtaan Lisäasetukset - ja valitse Salli julkisen asiakkaan työnkulut-kohdassa Kyllä Ota käyttöön seuraavat mobiili- ja työpöytätyönkulut.

GraphQL-mallirajapinnan määrittäminen sovelluksen käyttöä varten

Kun Microsoft Entra -sovelluksesi on rekisteröity, tarvitset GraphQL-rajapinnan Fabricissa kyselyihin. Tämä osio opastaa sinua luomaan esimerkki-API:n käyttäen Fabricin julkisia juhlapäiviä koskevaa aineistoa. Tämä antaa sinulle toimivan API:n tunnistautumisen ja tietojen haun testaamiseen ilman, että sinun tarvitsee konfiguroida omia tietolähteitäsi.

Esimerkki-API paljastaa juhlapäivätiedot Lakehouse-taulukosta, jota React-sovelluksesi pyytää näyttääkseen yleiset vapaapäivät.

1. Valitse Fabric-portaalin aloitussivulla Tietotekniikka kuormitusten luettelosta.

2. Valitse Data Engineering -kokemuksessa Käytä mallia ja valitse Lakehouse-kohdassaYleiset vapaapäivät , jos haluat luoda automaattisesti uuden Lakehousen, jossa on yleisten vapaapäivien tiedot.

   

3. Luo uusi GraphQL-ohjelmointirajapinta noudattamalla ohjeita kohdassa Ohjelmointirajapinnan luominen GraphQL:lle ja valitse luomasi Lakehouse. Lisää yleiset vapaapäivät-taulukko, jotta asiakkaat voivat käyttää näitä tietoja.

   

4. Ennen React-sovelluksen rakentamista varmista, että API:si toimii oikein testaamalla sitä API-editorissa. Käytä seuraavaa kyselyä – tämä on sama kysely, jonka React-sovelluksesi suorittaa myöhemmin:

    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. Valitse Ohjelmointirajapintakohteen työkaluriviltä Kopioi päätepiste .

   

6. Valitse Kopioi linkki -näytössä Kopioi.

   

7. Tallenna Client ID ja Tenant ID Microsoft Entra -sovelluksesta sekä päätelaitteen URI:sta. Tarvitset nämä arvot, kun konfiguroit React-sovelluksen.

Kloonaa ja konfiguroi React-sovellus

Nyt kun Microsoft Entra -sovellus ja GraphQL API ovat käytössä, voit konfiguroida React-sovelluksen yhdistämään niihin. Sovellus käyttää Microsoft Authentication Libraryä (MSAL) tunnistautumisen hoitamiseen ja tekee GraphQL-pyyntöjä Bearer-tokeneilla.

1. Kloonaa näytevarasto GitHubista:

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

2. Siirry React-sovelluskansioon:

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

   Kansio sisältää täydellisen React-sovelluksen. Sinun tarvitsee vain muokata src/authConfig.js konfiguroidaksesi oman päätepisteesi ja tunnuksesi.

3. Avaa projekti koodieditorissasi:

   code .
   

4. Editorissa siirry kansioon src ja avaa authConfig.js.

5. Korvaa seuraavat paikkamerkkiarvot omiin tietoihisi:

   • Enter_the_GraphQL_Endpoint_Here - Korvaa GraphQL API -päätepisteesi Aseta esimerkki GraphQL API:sta sovelluksen käyttöön
   • Enter_the_Application_Id_Here - Korvaa sovellus (asiakas) -ID :llä Create a Microsoft Entra -sovelluksesta
   • Enter_the_Tenant_Info_Here - Korvaa Directory (tenant) ID :si Create a Microsoft Entra -sovelluksesta

   Tärkeää

   Samassa tiedostossa vakio loginRequest sisältää scope https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Tämä tarkka laajuus on tarpeen Fabric GraphQL -rajapintojen käyttämiseen. Älä poista tai muokkaa tätä tähtäintä; muussa tapauksessa todennus epäonnistuu.

6. Tallenna tiedosto.

7. Päätteelläsi siirry projektin juurikansioon ja suorita:

   npm install
   

   Tämä asentaa kaikki tarvittavat riippuvuudet.

Sovelluksen testaaminen

Kun sovellus on konfiguroitu, aja se paikallisesti varmistaaksesi, että kaikki toimii oikein:

1. Suorita terminaalissasi:

   npm start
   

   Tämä komento käynnistää kehityspalvelimen ja avaa sovelluksen selaimessasi.

2. Suorita tunnistautumisprosessi, kun sovellus latautuu kohdassa http://localhost:3000. Seuraa sisäänkirjautumisvaiheita, jotka on kuvattu tutoriaaliosiossa Kutsu API sovelluksesta.

3. Kun olet kirjautunut onnistuneesti, valitse Query Fabric API for GraphQL Data -painike. Tämä käynnistää tunnistautumisprosessin, hankkii pääsytunnuksen ja suorittaa GraphQL-kyselyn Fabric-rajapintaa vastaan.

   

4. Jos kaikki on konfiguroitu oikein, sovellus näyttää yleiset vapaapäivät taulukossa. Se vahvistaa, että:

   • Microsoft Entra -sovelluksellasi on oikeat oikeudet
   • Pääsytunnus saatiin onnistuneesti haltuunsa
   • GraphQL-rajapinta autentikoitui pyynnön
   • Kysely suoritettiin Lakehouse-dataa vastaan

   

Muut npm-komennot

Lisäksi npm start , ja npm installvoit käyttää näitä yleisiä npm-komentoja eri kehitystilanteissa:

• npm run dev - Vaihtoehtoinen tapa käynnistää kehityspalvelin
• npm run build - Luo optimoitu tuotantoversio sovelluksestasi
• npm run preview - Testaa tuotantoversio paikallisesti ennen käyttöönottoa
• npm test - Suorita automatisoituja testejä varmistaaksesi, että koodisi toimii oikein

Liittyvä sisältö

Nyt kun sinulla on toimiva sovellus yhdistettynä Fabric GraphQL API:hin, tutustu näihin resursseihin rakentaaksesi kehittyneempiä ratkaisuja:

• Luo API GraphQL:lle Fabricissa ja lisää dataa – Opi avaamaan omat tietolähteesi
• Kysy useita tietolähteitä Fabric API:ssa GraphQL :lle – Yhdistä eri lähteiden tiedot yhdeksi kyselyksi
• Fabric API for GraphQL -editori – testaa ja kehitä kyselyitä interaktiivisesti
• Create a Microsoft Entra app in Azure - Detailed guide for production app registration
• Microsoft Fabric GraphQL -näytteet – Selaa näytteitä useilla kielillä