Toepassingen verbinden met Fabric-API voor GraphQL

Door toepassingen te verbinden met de API van Fabric voor GraphQL kunnen uw web-, mobiele en back-endtoepassingen gegevensbronnen opvragen met behulp van een moderne, efficiënte API. Voor deze integratie is een juiste verificatie vereist via de Microsoft Entra-id en configuratie van uw toepassing om het GraphQL-eindpunt veilig aan te roepen.

In dit artikel wordt uitgelegd hoe u een React-toepassing verbindt met de Fabric GraphQL-API door:

1. Een Microsoft Entra-app maken en configureren voor verificatie
2. Een GraphQL-voorbeeld-API instellen in Fabric met gegevens om een query uit te voeren
3. Een volledige React-toepassing klonen en configureren vanuit GitHub
4. De geverifieerde verbinding testen

In de zelfstudie wordt React gebruikt, maar verificatieconcepten zijn van toepassing op elke taal. Zie de GitHub-opslagplaats Microsoft Fabric-voorbeelden voor voorbeelden in C#, Python of andere talen.

Wie moet toepassingen verbinden

Installatie van toepassingsverbindingen is essentieel voor:

• Web- en mobiele ontwikkelaars bouwen toepassingen die gegevens gebruiken uit Fabric Lakehouses en magazijnen
• Integratieontwikkelaars die Fabric-gegevens verbinden met aangepaste toepassingen en geautomatiseerde werkstromen
• Back-endontwikkelaars die services maken die integreren met het uniforme analyseplatform van Fabric
• Data engineers instellen geautomatiseerde gegevensverwerkingswerkstromen die Fabric-gegevens verbruiken via API's

Gebruik deze handleiding wanneer u toepassingen moet verifiëren en autoriseren voor toegang tot uw Fabric GraphQL-API's.

Vereisten

• Ontwikkelhulpprogramma's: u hebt Node.js (LTS-versie) en Visual Studio Code op uw computer geïnstalleerd.

• Voordat u verbinding maakt met een toepassing, moet u ervoor zorgen dat u een API voor GraphQL in Fabric hebt. Zie Een API voor GraphQL maken in Fabric en gegevens toevoegen voor meer informatie.

• Voor de API voor GraphQL moeten toepassingen Microsoft Entra gebruiken voor verificatie. Registreer en configureer uw toepassing om API-aanroepen uit te voeren op Fabric. Zie Een Microsoft Entra-app maken in Azure voor meer informatie.

• De geverifieerde referentie (gebruikers-principal, service-principal of beheerde identiteit) die de API aanroept, moet uitvoermachtigingen hebben voor de GraphQL-API (optie Query's en Mutaties uitvoeren bij het toevoegen van directe toegangsmachtigingen). Als u eenmalige aanmelding (SSO) gebruikt als connectiviteitsoptie in de API, moet u ervoor zorgen dat de referentie lees- of schrijfmachtigingen heeft in de gekozen gegevensbron. Zie Verbinding maken met een gegevensbron en uw schemabouwen voor meer informatie.

Samenvatting van verificatie en machtigingen

Toegang tot de GraphQL-API vereist de juiste verificatie en autorisatie op api-niveau en het onderliggende gegevensbronniveau. U kunt zich verifiëren met behulp van een gebruikers-principal (die een afzonderlijke gebruiker vertegenwoordigt) of een service-principal (die een toepassing of service vertegenwoordigt). Voor gegevensbronconnectiviteit kunt u eenmalige aanmelding (SSO) gebruiken waarbij de identiteit van de beller wordt doorgegeven aan de gegevensbron of opgeslagen referenties waarbij een vooraf geconfigureerde verbinding wordt gebruikt.

De volgende tabel bevat een overzicht van de verschillende ondersteunde verificatiescenario's en de minimaal vereiste machtigingen voor clients die toegang hebben tot de GraphQL-API:

Een Microsoft Entra-app maken

Voordat uw toepassing de Fabric GraphQL-API kan aanroepen, moet u deze registreren in Microsoft Entra ID. Met deze registratie maakt u een identiteit voor uw toepassing en definieert u welke machtigingen deze nodig heeft. Het registratieproces genereert een client-id (toepassings-id) en brengt de verificatiestroom vast die uw app gebruikt om toegangstokens te verkrijgen.

Voor React-toepassingen configureert u spa-instellingen (single-page application) die gebruikmaken van de PKCE-stroom: een veilige verificatiemethode die is ontworpen voor browser-apps waar clientgeheimen niet veilig kunnen worden opgeslagen.

1. Registreer een toepassing met behulp van de stappen die worden beschreven in Quickstart: Een toepassing registreren bij het Microsoft Identity Platform.

2. De waarden voor toepassing-ID (client) en directory-ID (tenant) van Microsoft Entra worden weergegeven in het vak Samenvatting. Noteer deze waarden omdat u ze nodig hebt wanneer u de React-toepassing configureert.

3. Configureer API-machtigingen zodat uw toepassing toegang heeft tot de Fabric GraphQL-API. Onder de lijst Beheren, selecteer API-machtigingenen vervolgens Machtiging toevoegen.

4. Voeg de PowerBI-service toe, selecteer Gedelegeerde machtigingen en selecteer GraphQLApi.Execute.All-machtigingen . Met deze machtiging kan uw toepassing query's en mutaties uitvoeren namens de aangemelde gebruiker. Controleer of beheerderstoestemming niet is vereist.

5. Ga terug naar de lijst Beheren en selecteer Verificatie>een platformtoepassing> metéén pagina toevoegen.

6. Voeg voor lokale ontwikkelingsdoeleinden onder http://localhost:3000 toe en controleer of de toepassing is ingeschakeld voor de autorisatiecodestroom met Proof Key for Code Exchange (PKCE). Selecteer de knop Configureren om uw wijzigingen op te slaan. Als de toepassing een fout krijgt met betrekking tot cross-origin-aanvragen, voegt u het platform voor mobiele toepassingen en desktoptoepassingen toe in de vorige stap met dezelfde omleidings-URI.

7. Ga terug naar verificatie, schuif omlaag naar geavanceerde instellingen en selecteer onder Toestaan van openbare clientstromen, Ja voor inschakelen van de volgende mobiele en desktopstromen.

Een GraphQL-voorbeeld-API instellen voor toegang tot toepassingen

Wanneer uw Microsoft Entra-app is geregistreerd, hebt u een GraphQL-API in Fabric nodig om een query uit te voeren. In deze sectie wordt uitgelegd hoe u een voorbeeld-API maakt met behulp van de gegevensset openbare feestdagen van Fabric. Hiermee beschikt u over een werkende API om verificatie en het ophalen van gegevens te testen zonder dat u uw eigen gegevensbronnen hoeft te configureren.

De voorbeeld-API toont vakantiegegevens uit een Lakehouse-tabel, waarop uw React-toepassing query's moet uitvoeren om openbare feestdagen weer te geven.

1. Selecteer op de startpagina van de Fabric-portal Data-engineer ing in de lijst met workloads.

2. Selecteer in de data engineering-ervaring een voorbeeld gebruiken en selecteer onder Lakehouseopenbare feestdagen om automatisch een nieuw Lakehouse te maken met gegevens over openbare feestdagen.

   

3. Volg de stappen van Een API voor GraphQL maken om een nieuwe GraphQL-API te maken en selecteer het Lakehouse dat u hebt gemaakt. Voeg de tabel openbare feestdagen toe zodat clients toegang hebben tot deze gegevens.

   

4. Controleer voordat u de React-toepassing bouwt of uw API correct werkt door deze te testen in de API-editor. Gebruik de volgende query: dit is dezelfde query die uw React-toepassing later uitvoert:

    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. Selecteer Eindpunt kopiëren op de werkbalk van het API-item.

   

6. Selecteer Kopiëren in hetscherm Koppeling kopiëren.

   

7. Noteer de client-id en tenant-id van de Microsoft Entra-app en de eindpunt-URI. U hebt deze waarden nodig wanneer u de React-toepassing configureert.

De React-toepassing klonen en configureren

Nu u de Microsoft Entra-app en GraphQL-API hebt ingesteld, kunt u een React-toepassing configureren om er verbinding mee te maken. De toepassing maakt gebruik van Microsoft Authentication Library (MSAL) voor het afhandelen van verificatie en het maken van GraphQL-aanvragen met Bearer-tokens.

1. Kloon de opslagplaats met voorbeelden vanuit GitHub:

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

2. Navigeer naar de React-applicatiemap:

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

   De map bevat een volledige React-toepassing. U hoeft alleen te bewerken src/authConfig.js om uw specifieke eindpunt en referenties te configureren.

3. Open het project in de code-editor:

   code .
   

4. Navigeer in uw editor naar de src map en open authConfig.js.

5. Vervang de volgende waarden voor tijdelijke aanduidingen door uw specifieke gegevens:

   • Enter_the_GraphQL_Endpoint_Here - Vervang door uw GraphQL API-eindpunt van het instellen van een GraphQL-voorbeeld-API voor toegang tot toepassingen
   • Enter_the_Application_Id_Here - Vervang door uw toepassings-id (client) van Een Microsoft Entra-app maken
   • Enter_the_Tenant_Info_Here - Vervangen door uw directory-id (tenant) van Een Microsoft Entra-app maken

   Belangrijk

   In hetzelfde bestand bevat de loginRequest constante het bereik https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Dit exacte bereik is vereist voor toegang tot Fabric GraphQL-API's. Verwijder of wijzig dit bereik niet; anders mislukt de verificatie.

6. Sla het bestand op.

7. Navigeer in de terminal naar de hoofdmap van het project en voer het volgende uit:

   npm install
   

   Hiermee worden alle vereiste afhankelijkheden geïnstalleerd.

De toepassing testen

Als de toepassing is geconfigureerd, voert u deze lokaal uit om te controleren of alles correct werkt:

1. Voer in uw terminal het volgende uit:

   npm start
   

   Met deze opdracht wordt de ontwikkelserver gestart en wordt de toepassing in uw browser geopend.

2. Voltooi de verificatiestroom bij het laden van de toepassing op http://localhost:3000. Volg de aanmeldingsstappen die worden beschreven in de zelfstudiesectie De API aanroepen vanuit de toepassing.

3. Nadat u zich hebt aangemeld, selecteert u de knop Query Fabric-API voor GraphQL-gegevens . Hiermee wordt de verificatiestroom geactiveerd, wordt een toegangstoken verkregen en wordt de GraphQL-query uitgevoerd op uw Fabric-API.

   

4. Als alles correct is geconfigureerd, geeft de toepassing openbare feestdagen weer in een tabel. Dit bevestigt dat:

   • Uw Microsoft Entra-app heeft de juiste machtigingen
   • Het toegangstoken is verkregen
   • De GraphQL-API heeft de aanvraag geverifieerd
   • De query uitgevoerd op de Lakehouse-gegevens

   

Andere NPM-opdrachten

Naast npm start en npm installkunt u deze algemene NPM-opdrachten gebruiken voor verschillende ontwikkelscenario's:

• npm run dev - Alternatieve manier om de ontwikkelserver te starten
• npm run build - Een geoptimaliseerde productie-build van uw toepassing maken
• npm run preview - Test de productiebuild lokaal voordat u implementeert
• npm test - Voer geautomatiseerde tests uit om te controleren of uw code correct werkt

Gerelateerde inhoud

Nu u een werkende toepassing hebt die is verbonden met uw Fabric GraphQL-API, kunt u deze resources verkennen om geavanceerdere oplossingen te bouwen:

• Een API voor GraphQL maken in Fabric en gegevens toevoegen - Informatie over het beschikbaar maken van uw eigen gegevensbronnen
• Query's uitvoeren op meerdere gegevensbronnen in fabric-API voor GraphQL - Gegevens uit verschillende bronnen in één query combineren
• Fabric-API voor GraphQL-editor - Query's interactief testen en ontwikkelen
• Een Microsoft Entra-app maken in Azure - Gedetailleerde handleiding voor registratie van productie-apps
• Microsoft Fabric GraphQL-voorbeelden - Bladeren in voorbeelden in meerdere talen