Ansluta program till Fabric API för GraphQL

Genom att ansluta program till Fabrics API för GraphQL kan dina webb-, mobil- och serverdelsprogram köra frågor mot Fabric-datakällor med hjälp av ett modernt, effektivt API. Den här integreringen kräver korrekt autentisering via Microsoft Entra-ID och konfiguration av ditt program för att anropa GraphQL-slutpunkten på ett säkert sätt.

Den här artikeln beskriver hur du ansluter ett React-program till Fabric GraphQL API genom att:

1. Skapa och konfigurera en Microsoft Entra-app för autentisering
2. Konfigurera ett exempel-API för GraphQL i Fabric med data som kan hämtas
3. Klona och konfigurera en fullständig React-applikation från GitHub
4. Att testa den autentiserade anslutningen

I självstudien används React, men autentiseringsbegrepp gäller för alla språk. Exempel på C#, Python eller andra språk finns i GitHub-lagringsplatsen Microsoft Fabric Samples.

Vem behöver ansluta applikationer

Konfiguration av programanslutning är viktigt för:

• Webb- och mobilutvecklare skapar program som använder data från Fabric lakehouses och datalager
• Integrationsutvecklare som ansluter Infrastrukturdata till anpassade program och automatiserade arbetsflöden
• Backend-utvecklare skapar tjänster som integreras med Fabrics enhetliga analysplattform
• Datatekniker konfigurerar automatiserade arbetsflöden för databearbetning som använder Infrastrukturdata via API:er

Använd den här guiden när du behöver autentisera och auktorisera program för att få åtkomst till dina Fabric GraphQL-API:er.

Förutsättningar

• Utvecklingsverktyg: Du behöver Node.js (LTS-version) och Visual Studio Code installerade på datorn.

• Kontrollera att du har ett API för GraphQL i Infrastrukturresurser innan du ansluter ett program. Mer information finns i Skapa ett API för GraphQL i Infrastrukturresurser och lägga till data.

• API:et för GraphQL kräver att program använder Microsoft Entra för autentisering. Registrera och konfigurera ditt program för att utföra API-anrop mot Fabric. Mer information finns i Skapa en Microsoft Entra-app i Azure.

• Den autentiserade legitimationsuppgiften (användarens huvudnamn, tjänstens huvudnamn eller hanterade identitet) som anropar API:et behöver Kör-behörigheter för GraphQL-API:et (optionen för att köra frågor och mutationer när du lägger till direktåtkomstbehörigheter). Om du använder enkel inloggning (SSO) som anslutningsalternativ i API:et kontrollerar du att autentiseringsuppgifterna har läs- eller skrivbehörigheter i den valda datakällan. Mer information finns i Anslut till en datakälla och skapa ditt schema.

Sammanfattning av autentisering och behörigheter

Åtkomst till GraphQL-API:et kräver korrekt autentisering och auktorisering på både API-nivå och underliggande datakällnivå. Du kan autentisera med antingen ett användarhuvudnamn (som representerar en enskild användare) eller ett huvudnamn för tjänsten (som representerar ett program eller en tjänst). För datakällans anslutning kan du använda enkel inloggning (SSO) där anroparens identitet skickas till datakällan eller sparade autentiseringsuppgifter där en förkonfigurerad anslutning används.

I följande tabell sammanfattas de olika autentiseringsscenarier som stöds och den lägsta behörighet som krävs för klienter som har åtkomst till GraphQL-API:et:

API-anropare	Anslutningar för datakälla	Nödvändiga GraphQL API-behörigheter	Nödvändiga behörigheter för datakälla	Microsoft Entra-appomfång
Användarens huvudnamn (UPN)	Enkel inloggning (SSO)	Köra frågor och mutationer på API-nivå	Lämpliga läs-/skrivbehörigheter som beviljats UPN i datakällan	GraphQLApi.Execute.All
Tjänstens huvudnamn (SPN)	Enkel inloggning (SSO)	Köra frågor och mutationer på API-nivå	Lämpliga läs-/skrivbehörigheter som beviljats SPN i datakällan	Ej tillämpligt
Användarens huvudnamn (UPN)	Sparade autentiseringsuppgifter	Köra frågor och mutationer på API-nivå	Lämpliga läs-/skrivbehörigheter som beviljats till den sparade autentiseringsuppgiften (anslutningen) i datakällan	GraphQLApi.Execute.All
Tjänstens huvudnamn (SPN)	Sparade autentiseringsuppgifter	Köra frågor och mutationer på API-nivå	Lämpliga läs-/skrivbehörigheter som beviljats SPN i datakällan	Ej tillämpligt

Skapa en Microsoft Entra-app

Innan programmet kan anropa Fabric GraphQL-API:et måste du registrera det i Microsoft Entra-ID. Den här registreringen skapar en identitet för ditt program och definierar vilka behörigheter det behöver. Registreringsprocessen genererar ett klient-ID (programidentifierare) och upprättar det autentiseringsflöde som appen använder för att hämta åtkomsttoken.

För React-program konfigurerar du spa-inställningar (single-page application) som använder PKCE-flödet – en säker autentiseringsmetod som är utformad för webbläsarbaserade appar där klienthemligheter inte kan lagras på ett säkert sätt.

1. Registrera ett program med hjälp av stegen som beskrivs i snabbstarten : Registrera ett program med Microsofts identitetsplattform.

2. Värdena för Microsoft Entra-app Applikation-ID (klient) och Katalog-ID (klientorganisation) visas i rutan Sammanfattning. Registrera dessa värden eftersom du behöver dem när du konfigurerar React-programmet.

3. Konfigurera API-behörigheter så att ditt program kan komma åt Fabric GraphQL-API:et. I listan Hantera väljer du API-behörigheteroch sedan Lägg till behörighet.

4. Lägg till PowerBI-tjänsten, välj Delegerade behörigheter och välj GraphQLApi.Execute.All-behörigheter . Med den här behörigheten kan ditt program köra frågor och mutationer för den inloggade användarens räkning. Bekräfta att administratörsmedgivande inte krävs.

5. Gå tillbaka till listan Hantera och välj Autentisering>Lägg till ett plattformsprogram>för en sida.

6. För lokal utveckling lägger du till http://localhost:3000 under Omdirigerings-URI:er och bekräftar att programmet är aktiverat för auktoriseringskodflödet med Proof Key for Code Exchange (PKCE). Välj knappen Konfigurera för att spara ändringarna. Om applikationen stöter på ett fel relaterat till begäranden mellan olika ursprung, lägger du till plattformen Mobil- och skrivbordsapplikationer i föregående steg med samma omdirigerings-URI.

7. Tillbaka till Authenticationrullar du ned till Avancerade inställningar och under Tillåt offentliga klientflödenväljer du Ja för Aktivera följande mobil- och skrivbordsflöden.

Konfigurera ett GraphQL-exempel-API för programåtkomst

När din Microsoft Entra-app är registrerad behöver du ett GraphQL-API i Fabric för att fråga. Det här avsnittet beskriver hur du skapar ett exempel-API med hjälp av Fabrics datauppsättning för helgdagar. Detta ger dig ett fungerande API för att testa autentisering och datahämtning utan att behöva konfigurera dina egna datakällor.

Exempel-API:et exponerar semesterdata från en Lakehouse-tabell, som ditt React-program frågar för att visa helgdagar.

1. På startsidan för Infrastrukturportalen väljer du Dataingenjör ing i listan över arbetsbelastningar.

2. I Data Engineering-upplevelsen väljer du Använd ett exempel och under Lakehouse väljer du Helgdagar för att automatiskt skapa ett nytt Lakehouse med data om helgdagar.

   

3. Följ stegen från Skapa ett API för GraphQL för att skapa ett nytt GraphQL-API och välj det Lakehouse som du skapade. Lägg till tabellen för helgdagar så att klienter kan komma åt dessa data.

   

4. Innan du skapar React-programmet kontrollerar du att api:et fungerar korrekt genom att testa det i API-redigeraren. Använd följande fråga – det här är samma fråga som React-programmet kör senare:

    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älj Kopiera slutpunkt i API-objektets verktygsfält.

   

6. På skärmen Kopiera länk väljer du Kopiera.

   

7. Registrera klient-ID och klient-ID från Microsoft Entra-appen och slutpunkts-URI:n. Du behöver dessa värden när du konfigurerar React-programmet.

Klona och konfigurera React-programmet

Nu när du har konfigurerat Microsoft Entra-appen och GraphQL API kan du konfigurera ett React-program för att ansluta till dem. Programmet använder Microsoft Authentication Library (MSAL) för att hantera autentisering och gör GraphQL-begäranden med ägartoken.

1. Klona exempellagringsplatsen från GitHub:

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

2. Gå till React-applikationsmappen

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

   Mappen innehåller ett fullständigt React-program. Du behöver bara redigera src/authConfig.js för att konfigurera din specifika slutpunkt och dina autentiseringsuppgifter.

3. Öppna projektet i kodredigeraren:

   code .
   

4. I redigeringsprogrammet navigerar du till src mappen och öppnar authConfig.js.

5. Ersätt följande platshållarvärden med din specifika information:

   • Enter_the_GraphQL_Endpoint_Here – Ersätt med GraphQL API-slutpunkten från Konfigurera ett GraphQL-exempel-API för programåtkomst
   • Enter_the_Application_Id_Here – Ersätt med ditt program-ID (klient)-ID från Skapa en Microsoft Entra-app
   • Enter_the_Tenant_Info_Here – Ersätt med ditt katalog-ID (klient)-ID från Skapa en Microsoft Entra-app

   Viktigt!

   I samma fil innehåller konstanten loginRequest omfånget https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Det här exakta omfånget krävs för åtkomst till Fabric GraphQL-API:er. Ta inte bort eller ändra inte det här omfånget. annars misslyckas autentiseringen.

6. Spara filen.

7. I terminalen går du till projektrotmappen och kör:

   npm install
   

   Detta installerar alla nödvändiga beroenden.

Testa programmet

När programmet har konfigurerats kör du det lokalt för att kontrollera att allt fungerar korrekt:

1. Kör kommandot i terminalen:

   npm start
   

   Det här kommandot startar utvecklingsservern och öppnar programmet i webbläsaren.

2. Slutför autentiseringsflödet när programmet startar på http://localhost:3000. Följ inloggningsstegen som beskrivs i självstudieavsnittet Anropa API:et från programmet.

3. När du har loggat in väljer du knappen Query Fabric API för GraphQL Data . Detta utlöser autentiseringsflödet, hämtar en åtkomsttoken och kör GraphQL-frågan mot fabric-API:et.

   

4. Om allt är korrekt konfigurerat visar programmet helgdagar i en tabell. Detta bekräftar att:

   • Din Microsoft Entra-app har rätt behörigheter
   • Åtkomsttoken har framgångsrikt hämtats
   • GraphQL API autentiserade begäran
   • Frågan som körs mot Lakehouse-data

   

Andra npm-kommandon

Utöver npm start och npm installkan du använda dessa vanliga npm-kommandon för olika utvecklingsscenarier:

• npm run dev – Alternativt sätt att starta utvecklingsservern
• npm run build – Skapa en optimerad produktionsversion av ditt program
• npm run preview – Testa produktionsversionen lokalt innan du distribuerar
• npm test – Kör automatiserade tester för att verifiera att koden fungerar korrekt

Relaterat innehåll

Nu när du har ett fungerande program anslutet till ditt Fabric GraphQL-API kan du utforska dessa resurser för att skapa mer avancerade lösningar:

• Skapa ett API för GraphQL i Fabric och lägg till data – Lär dig hur du exponerar dina egna datakällor
• Fråga flera datakällor i Fabric API för GraphQL – Kombinera data från olika källor i en enda fråga
• Infrastruktur-API för GraphQL-redigerare – Testa och utveckla frågor interaktivt
• Skapa en Microsoft Entra-app i Azure – Detaljerad guide för registrering av produktionsappar
• Microsoft Fabric GraphQL-exempel – Bläddra bland exempel på flera språk