Koble programmer til Fabric API for GraphQL

Å koble applikasjoner til Fabrics API for GraphQL gjør det mulig for web-, mobil- og backend-applikasjoner å spørre Fabric-datakilder ved hjelp av et moderne, effektivt API. Denne integrasjonen krever riktig autentisering via Microsoft Entra-ID og konfigurasjon av applikasjonen din for å kunne kalle GraphQL-endepunktet sikkert.

Denne artikkelen guider deg gjennom hvordan du kobler en React-applikasjon til Fabric GraphQL API ved å:

1. Opprette og konfigurere en Microsoft Entra-app for autentisering
2. Oppsett av et eksempel på GraphQL API i Fabric med data for å spørre
3. Kloning og konfigurasjon av en komplett React-applikasjon fra GitHub
4. Testing av den autentiserte tilkoblingen

Opplæringen bruker React, men autentiseringskonsepter gjelder for alle språk. For eksempler i C#, Python eller andre språk, se Microsoft Fabric Samples GitHub-repositoriet.

Hvem trenger å koble applikasjoner sammen

Oppsett av applikasjonstilkobling er essensielt for:

• Web- og mobilutviklere som bygger applikasjoner som konsumerer data fra Fabric-innsjøhus og lagre
• Integrasjonsutviklere kobler Fabric-data til tilpassede applikasjoner og automatiserte arbeidsflyter
• Backend-utviklere som lager tjenester som integreres med Fabrics enhetlige analyseplattform
• Dataingeniører som setter opp automatiserte databehandlingsflyter som konsumerer Fabric-data via API-er

Bruk denne guiden når du trenger å autentisere og autorisere applikasjoner for å få tilgang til dine Fabric GraphQL-API-er.

Forutsetning

• Utviklingsverktøy: Du trenger Node.js(LTS-versjonen ) og Visual Studio Code installert på maskinen din.

• Før du kobler til et program, sørg for at du har et API for GraphQL i Fabric. Hvis du vil ha mer informasjon, kan du se Opprette en API for GraphQL i Fabric og legge til data.

• API-en for GraphQL krever at programmer bruker Microsoft Entra for godkjenning. Registrer og konfigurer programmet til å utføre API-kall mot Fabric. Hvis du vil ha mer informasjon, kan du se Opprette en Microsoft Entra-app i Azure.

• Den godkjente legitimasjonen (brukerkontohaver, tjenestekontohaver eller administrert identitet) som kaller API-en, må ha kjøretillatelser for GraphQL-API-en (alternativet Kjør spørringer og mutasjoner når du legger til direkte tilgangstillatelser). Hvis du bruker enkel pålogging (SSO) som tilkoblingsalternativ i API-en, må du kontrollere at legitimasjonen har lese- eller skrivetillatelser i den valgte datakilden. Hvis du vil ha mer informasjon, kan du se Koble til en datakilde og bygge skjemaet.

Sammendrag av autentisering og tillatelser

Tilgang til GraphQL API krever riktig autentisering og autorisasjon både på API-nivå og på underliggende datakildenivå. Du kan autentisere ved å bruke enten en user principal (som representerer en individuell bruker) eller en service principal (som representerer en applikasjon eller tjeneste). For datakildetilkobling kan du bruke single sign-on (SSO) hvor innringerens identitet sendes videre til datakilden, eller lagrede legitimasjoner der en forhåndskonfigurert tilkobling brukes.

Følgende tabell oppsummerer de ulike støttede autentiseringsscenariene og minimumskravene for klienter som får tilgang til GraphQL API-et:

API-anroper	Datakildetilkobling	Nødvendige GraphQL API-tillatelser	Nødvendige datakildetillatelser	Microsoft Entra app-omfang
Brukerkontohaver (UPN)	Enkel pålogging (SSO)	Kjør spørringer og mutasjoner på API-nivå	Riktige lese-/skrivetillatelser gitt til UPN på datakilden	GraphQLApi.Execute.All
Tjenestekontohaver (SPN)	Enkel pålogging (SSO)	Kjør spørringer og mutasjoner på API-nivå	Riktige lese-/skrivetillatelser som gis til SPN-en på datakilden	Ikke aktuelt
Brukerkontohaver (UPN)	Lagret legitimasjon	Kjør spørringer og mutasjoner på API-nivå	Riktige lese-/skrivetillatelser som gis til den lagrede legitimasjonen (tilkoblingen) i datakilden	GraphQLApi.Execute.All
Tjenestekontohaver (SPN)	Lagret legitimasjon	Kjør spørringer og mutasjoner på API-nivå	Riktige lese-/skrivetillatelser som gis til SPN-en på datakilden	Ikke aktuelt

Opprette en Microsoft Entra-app

Før applikasjonen din kan kalle Fabric GraphQL API, må du registrere den i Microsoft Entra ID. Denne registreringen oppretter en identitet for applikasjonen din og definerer hvilke tillatelser den trenger. Registreringsprosessen genererer en klient-ID (applikasjonsidentifikator) og etablerer autentiseringsflyten appen din bruker for å få tilgang til tokens.

For React-applikasjoner konfigurerer du enkeltsideapplikasjonsinnstillinger (SPA) som bruker PKCE-flyten – en sikker autentiseringsmetode designet for nettleserbaserte apper hvor klienthemmeligheter ikke kan lagres trygt.

1. Registrer et program ved hjelp av trinnene som er beskrevet på Hurtigstart: Registrer et program med Microsoft-identitetsplattformen.

2. Verdiene for Microsoft Entra-appens program-ID (klient) og katalog-ID (leier) vises i Sammendrag-boksen. Registrer disse verdiene fordi du trenger dem når du konfigurerer React-applikasjonen.

3. Konfigurer API-tillatelser slik at applikasjonen din kan få tilgang til Fabric GraphQL API. Under listen Behandle velger du API-tillatelser, og deretter Legg til tillatelse.

4. Legg til PowerBI-tjenesten, velg Delegerte tillatelser, og velg GraphQLApi.Execute.All-tillatelser . Denne tillatelsen lar applikasjonen din utføre spørringer og mutasjoner på vegne av den innloggede brukeren. Bekreft at administratorsamtykke ikke er nødvendig.

5. Gå tilbake til Behandle-listen , velg Godkjenning>Legg til en plattform>Enkeltsideprogram.

6. For lokale utviklingsformål legger du til http://localhost:3000 under Omadresser URIer og bekrefter at programmet er aktivert for autorisasjonskodeflyten med Proof Key for Code Exchange (PKCE). Velg Konfigurer-knappen for å lagre endringene. Hvis programmet støter på en feil relatert til forespørsler om kryssopprinnelse, legger du til plattformen for mobil- og skrivebordsprogrammer i forrige trinn med samme omdirigerings-URI.

7. Rull ned til Avanserte innstillinger, og velg Ja for Aktiver følgendeunder Tillat offentlige klientflyter.

Konfigurere et eksempel på GraphQL API for programtilgang

Med Microsoft Entra-appen din registrert, trenger du et GraphQL API i Fabric for å spørre. Denne delen guider deg gjennom å lage et eksempel-API ved bruk av Fabrics datasett for offentlige helligdager. Dette gir deg et fungerende API for å teste autentisering og datahenting uten å måtte konfigurere dine egne datakilder.

Eksempel-API-et eksponerer høytidsdata fra en Lakehouse-tabell, som React-applikasjonen din spør i for å vise offentlige helligdager.

1. Velg Dataingeniør fra listen over arbeidsbelastninger på hjemmesiden for Fabric-portalen.

2. I Data Engineering-opplevelsen velger du Bruk et eksempel, og under Lakehouse velger du Helligdager for automatisk å opprette et nytt Lakehouse med helligdagerdata.

   

3. Følg trinnene fra Opprett en API for GraphQL for å opprette en ny GraphQL API og velg Lakehouse du opprettet. Legg til helligdager-tabellen slik at klienter kan få tilgang til disse dataene.

   

4. Før du bygger React-applikasjonen, sjekk at API-et ditt fungerer riktig ved å teste det i API-editoren. Bruk følgende spørring—dette er den samme spørringen som React-applikasjonen din kjører senere:

    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. Velg Kopier endepunkt på verktøylinjen for API-elementet.

   

6. Velg Kopier i skjermbildet Kopier kobling.

   

7. Registrer klient-ID og leietaker-ID fra Microsoft Entra-appen og endepunktets URI. Du trenger disse verdiene når du konfigurerer React-applikasjonen.

Klon og konfigurer React-applikasjonen

Nå som du har satt opp Microsoft Entra-appen og GraphQL API, kan du konfigurere en React-applikasjon til å koble til dem. Applikasjonen bruker Microsoft Authentication Library (MSAL) for å håndtere autentisering og gjør GraphQL-forespørsler med Bearer-tokens.

1. Klon samples-repositoriet fra GitHub:

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

2. Naviger til React-applikasjonsmappen:

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

   Mappen inneholder et komplett React-program. Du trenger bare å redigere src/authConfig.js for å konfigurere din spesifikke endepunkt og legitimasjon.

3. Åpne prosjektet i kodeeditoren din:

   code .
   

4. I editoren din navigerer du til src mappen og åpner authConfig.js.

5. Erstatt følgende plassholderverdier med dine spesifikke detaljer:

   • Enter_the_GraphQL_Endpoint_Here - Erstatte med ditt GraphQL API-endepunkt fra Sett opp et eksempel GraphQL API for applikasjonstilgang
   • Enter_the_Application_Id_Here - Erstatt med din applikasjons-ID (klient-ID) fra Opprett en Microsoft Entra-app
   • Enter_the_Tenant_Info_Here - Erstatt med din Directory (tenant) ID fra Opprett en Microsoft Entra-app

   Viktig!

   I samme fil inkluderer konstanten loginRequest omfanget https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Dette eksakte omfanget kreves for å få tilgang til Fabric GraphQL API-er. Ikke fjern eller modifiser dette teleskopet; ellers feiler autentiseringen.

6. Lagre filen.

7. I terminalen din, naviger til prosjektets rotmappe og kjør:

   npm install
   

   Dette installerer alle nødvendige avhengigheter.

Test programmet

Med applikasjonen konfigurert, kjør den lokalt for å verifisere at alt fungerer som det skal:

1. I terminalen din, kjør:

   npm start
   

   Denne kommandoen starter utviklingsserveren og åpner applikasjonen i nettleseren din.

2. Fullfør autentiseringsflyten når applikasjonen lastes ved http://localhost:3000. Følg innloggingstrinnene beskrevet i veiledningsdelen: Kall API-et fra applikasjonen.

3. Etter at du har logget inn, velg knappen Query Fabric API for GraphQL Data . Dette utløser autentiseringsflyten, skaffer en tilgangstoken, og kjører GraphQL-spørringen mot Fabric API-et ditt.

   

4. Hvis alt er riktig konfigurert, viser applikasjonen offentlige fridager i en tabell. Dette bekrefter at:

   • Microsoft Entra-appen din har riktige tillatelser
   • Tilgangstokenet ble vellykket anskaffet
   • GraphQL API autentiserte forespørselen
   • Spørringen ble utført mot Lakehouse-dataene

   

Andre npm-kommandoer

Utover npm start og npm install, kan du bruke disse vanlige npm-kommandoene for ulike utviklingsscenarier:

• npm run dev - Alternativ måte å starte utviklingsserveren på
• npm run build - Lag en optimalisert produksjonsbygg av applikasjonen din
• npm run preview - Test produksjonsversjonen lokalt før utrulling
• npm test - Kjør automatiserte tester for å verifisere at koden din fungerer riktig

Relatert innhold

Nå som du har en fungerende applikasjon koblet til ditt Fabric GraphQL API, utforsk disse ressursene for å bygge mer sofistikerte løsninger:

• Lag et API for GraphQL i Fabric og legg til data – Lær hvordan du eksponerer dine egne datakilder
• Spør flere datakilder i Fabric API for GraphQL - Kombiner data fra forskjellige kilder i én enkelt spørring
• Fabric API for GraphQL-editor – Test og utvikle spørringer interaktivt
• Lag en Microsoft Entra-app i Azure – Detaljert guide for registrering av produksjonsapplikasjoner
• Microsoft Fabric GraphQL-eksempler - Bla gjennom eksempler på flere språk