Del via

Opret forbindelse mellem programmer og Fabric API til GraphQL

Ved at forbinde applikationer til Fabrics API for GraphQL kan dine web-, mobil- og backend-applikationer forespørge Fabric-datakilder ved hjælp af en moderne og effektiv API. Denne integration kræver korrekt autentificering via Microsoft Entra ID og konfiguration af din applikation for sikkert at kalde GraphQL-endpointet.

Denne artikel guider dig gennem at forbinde en React-applikation til Fabric GraphQL API ved at:

  1. Oprettelse og konfiguration af en Microsoft Entra-app til autentificering
  2. Opsætning af et eksempel på GraphQL API i Fabric med data til forespørgsel
  3. Kloning og konfiguration af en komplet React-applikation fra GitHub
  4. Test af den autentificerede forbindelse

Tutorialen bruger React, men autentificeringskoncepter gælder for alle programmer. For eksempler i C#, Python eller andre sprog, se Microsoft Fabric Samples GitHub-repositoryet.

Hvem skal forbinde applikationer

Opsætning af applikationsforbindelse er essentiel for:

  • Web- og mobiludviklere , der bygger applikationer, der forbruger data fra Fabric-søhuse og lagre
  • Integrationsudviklere , der forbinder Fabric-data til brugerdefinerede applikationer og automatiserede arbejdsgange
  • Backend-udviklere , der skaber tjenester, der integreres med Fabrics samlede analyseplatform
  • Dataingeniører , der opsætter automatiserede databehandlingsarbejdsgange, som forbruger Fabric-data via API'er

Brug denne guide, når du skal autentificere og godkende applikationer for at få adgang til dine Fabric GraphQL API'er.

Forudsætninger

  • Udviklingsværktøjer: Du skal have Node.js(LTS-version ) og Visual Studio Code installeret på din maskine.

  • Før du tilslutter et program, skal du sikre dig, at du har en API til GraphQL i Fabric. Du kan få flere oplysninger under Opret en API til GraphQL i Fabric, og tilføj data.

  • API'en til GraphQL kræver, at programmer bruger Microsoft Entra til godkendelse. Registrer og konfigurer dit program til at udføre API-kald mod Fabric. Du kan få flere oplysninger under Opret en Microsoft Entra-app i Azure.

  • De godkendte legitimationsoplysninger (brugerprincipal, tjenesteprincipal eller administreret identitet), der kalder API'en, skal have kørselstilladelser til GraphQL-API'en (indstillingen Kør forespørgsler og mutationer, når der tilføjes tilladelser til direkte adgang). Hvis du bruger enkeltlogon (SSO) som forbindelsesmulighed i API'en, skal du sikre dig, at legitimationsoplysningerne har læse- eller skrivetilladelser i den valgte datakilde. Du kan få flere oplysninger under Opret forbindelse til en datakilde, og opret dit skema.

Oversigt over autentificering og tilladelser

Adgang til GraphQL API'en kræver korrekt autentificering og autorisation både på API-niveau og på det underliggende datakilde-niveau. Du kan autentificere ved enten at bruge en brugerprincipal (der repræsenterer en individuel bruger) eller en serviceprincipal (der repræsenterer en applikation eller tjeneste). For datakildeforbindelse kan du bruge single sign-on (SSO), hvor opkalderens identitet sendes videre til datakilden, eller gemte legitimationsoplysninger , hvor en forudkonfigureret forbindelse bruges.

Følgende tabel opsummerer de forskellige understøttede autentificeringsscenarier og de minimumsnødvendige tilladelser for klienter, der tilgår GraphQL API'et:

API-kalder Datakilde-forbindelsen Påkrævede GraphQL API-tilladelser Påkrævede tilladelser til datakilder Microsoft Entra app-scope
Brugerprincip (UPN) Enkeltlogon (SSO) Kør forespørgsler og mutationer på API-niveau Passende læse-/skrivetilladelser givet til UPN ved datakilden GraphQLApi.Execute.All
Serviceleder (SPN) Enkeltlogon (SSO) Kør forespørgsler og mutationer på API-niveau Passende læse-/skrivetilladelser givet til SPN ved datakilden Ikke relevant
Brugerprincip (UPN) Gemte legitimationsoplysninger Kør forespørgsler og mutationer på API-niveau Passende læse-/skrivetilladelser givet til den gemte legitimation (forbindelsen) ved datakilden GraphQLApi.Execute.All
Serviceleder (SPN) Gemte legitimationsoplysninger Kør forespørgsler og mutationer på API-niveau Passende læse-/skrivetilladelser givet til SPN ved datakilden Ikke relevant

Opret en Microsoft Entra-app

Før din applikation kan kalde Fabric GraphQL API'en, skal du registrere den i Microsoft Entra ID. Denne registrering opretter en identitet for din applikation og definerer, hvilke tilladelser den har brug for. Registreringsprocessen genererer et klient-ID (applikationsidentifikator) og etablerer den autentificeringsflow, din app bruger til at opnå adgangstoks.

For React-applikationer konfigurerer du enkeltside-applikationsindstillinger (SPA), der bruger PKCE-flowet – en sikker autentificeringsmetode designet til browserbaserede apps, hvor klienthemmeligheder ikke kan gemmes sikkert.

  1. Registrer et program ved hjælp af de trin, der er beskrevet i Hurtig start: Registrer et program med Microsoft-identitetsplatformen.

  2. Værdierne for Microsoft Entra-appprogram-id (klient) og katalog-id (lejer) vises i feltet Oversigt. Registrer disse værdier, fordi du har brug for dem, når du konfigurerer React-applikationen.

  3. Konfigurér API-tilladelser, så din applikation kan få adgang til Fabric GraphQL API'en. På listen Administrer skal du vælge API-tilladelserog derefter Tilføj tilladelse.

  4. Tilføj PowerBI-tjenesten, vælg Delegerede tilladelser, og vælg GraphQLApi.Execute.All permissions. Denne tilladelse tillader din applikation at udføre forespørgsler og mutationer på vegne af den indloggede bruger. Bekræft, at administratorsamtykke ikke er påkrævet.

  5. Gå tilbage til listen Administrer , vælg Godkendelse>Tilføj en platform>Enkeltsidet program.

  6. I forbindelse med lokal udvikling skal du tilføje http://localhost:3000 under Omdirigerings-URI'er og bekræfte, at programmet er aktiveret for godkendelseskodeflowet med proof key for Code Exchange (PKCE). Vælg knappen Konfigurer for at gemme dine ændringer. Hvis programmet støder på en fejl, der er relateret til anmodninger på tværs af oprindelse, skal du tilføje platformen Mobil- og skrivebordsprogrammer i det forrige trin med den samme omdirigerings-URI.

  7. Gå tilbage til Godkendelse, rul ned til avancerede indstillinger, og under Tillad offentlige klientflowskal du vælge Ja for at Aktivér følgendepå mobilenheder og stationære computere .

Konfigurer en GraphQL-eksempel-API til programadgang

Med din Microsoft Entra-app registreret, skal du bruge et GraphQL API i Fabric for at forespørge. Denne sektion guider dig gennem oprettelsen af et eksempel på API ved brug af Fabrics offentlige helligdage-datasæt. Dette giver dig et fungerende API til at teste autentificering og datahentning uden at skulle konfigurere dine egne datakilder.

Eksempel-API'en eksponerer helligdagsdata fra en Lakehouse-tabel, som din React-applikation forespørger for at vise helligdage.

  1. Vælg Dataudvikler på listen over arbejdsbelastninger på startsiden for Fabric-portalen.

  2. I Data Engineering-oplevelsen skal du vælge Brug et eksempel og under Lakehouse skal du vælge Helligdage for automatisk at oprette et nyt Lakehouse med helligdagsdata.

    Skærmbillede ved valg af eksempeldata Lakehouse-indstillingen.

  3. Følg trinene fra Opret en API til GraphQL for at oprette en ny GraphQL API og vælg det Lakehouse, du oprettede. Tilføj tabellen over helligdage, så kunderne kan få adgang til disse data.

    Skærmbillede af tilføjelse af eksemplet Lakehouse som GraphQL-datakilde.

  4. Før du bygger React-applikationen, skal du sikre dig, at dit API fungerer korrekt ved at teste det i API-editoren. Brug følgende forespørgsel – dette er den samme forespørgsel, som din React-applikation udfø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. Vælg Kopiér slutpunkt på API-elementets værktøjslinje.

    Skærmbillede af værktøjslinjeindstillingerne for et API-element.

  6. Vælg Kopiér på skærmen Kopiér link.

    Skærmbillede af dialogboksen Kopiér link, der viser, hvor du skal vælge Kopiér.

  7. Optag klient-id og lejer-id fra Microsoft Entra-appen og endpoint-URI'en. Du har brug for disse værdier, når du konfigurerer React-applikationen.

Klon og konfigurér React-applikationen

Nu hvor du har Microsoft Entra-appen og GraphQL API'en sat op, kan du konfigurere en React-applikation til at forbinde til dem. Applikationen bruger Microsoft Authentication Library (MSAL) til at håndtere autentificering og laver GraphQL-forespørgsler med Bearer-tokens.

  1. Klon sample-repositoryet fra GitHub:

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

  2. Navigér til React-applikationsmappen:

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

    Mappen indeholder et komplet React-program. Du behøver kun at redigere src/authConfig.js for at konfigurere dit specifikke endpoint og dine legitimationsoplysninger.

  3. Åbn projektet i din kodeeditor:

    code .

  4. I din editor skal du navigere til src mappen og åbne authConfig.js.

  5. Erstat følgende pladsholderværdier med dine specifikke oplysninger:

    Important

    I samme fil inkluderer konstanten loginRequest omfanget https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Dette præcise omfang kræves for at få adgang til Fabric GraphQL API'er. Fjern eller ændr ikke dette teleskop; Ellers fejler autentificeringen.

  6. Gem filen.

  7. I din terminal skal du navigere til projektets rodmappe og køre:

    npm install

    Dette installerer alle nødvendige afhængigheder.

Test programmet

Når applikationen er konfigureret, kør den lokalt for at sikre, at alt fungerer korrekt:

  1. I din terminal, kør:

    npm start

    Denne kommando starter udviklingsserveren og åbner applikationen i din browser.

  2. Fuldfør autentificeringsflowet, når applikationen indlæses ved http://localhost:3000. Følg de login-trin, der er beskrevet i vejledningsafsnittet. Kald API'en fra applikationen.

  3. Efter at have logget ind med succes, vælg knappen Query Fabric API for GraphQL Data . Dette udløser autentificeringsflowet, erhverver en adgangstoken og udfører GraphQL-forespørgslen mod din Fabric API.

    Skærmbillede af React-eksempelappen efter login.

  4. Hvis alt er konfigureret korrekt, viser applikationen helligdage i en tabel. Dette bekræfter, at:

    • Din Microsoft Entra-app har de korrekte tilladelser
    • Adgangstokten blev med succes erhvervet
    • GraphQL API'et autentificerede anmodningen
    • Forespørgslen blev udført mod Lakehouse-dataene

    Skærmbillede af React-eksempelappen efter modtagelse af GraphQL-anmodningen.

Andre npm-kommandoer

Ud over npm start og npm install, kan du bruge disse almindelige npm-kommandoer til forskellige udviklingsscenarier:

  • npm run dev - Alternativ måde at starte udviklingsserveren på
  • npm run build - Opret en optimeret produktionsbuild af din applikation
  • npm run preview - Test produktionsbuildet lokalt før udrulning
  • npm test - Kør automatiserede tests for at verificere, at din kode fungerer korrekt

Relateret indhold

Nu hvor du har en fungerende applikation forbundet til din Fabric GraphQL API, kan du udforske disse ressourcer for at bygge mere avancerede løsninger:

  • Last updated on