Dela via

Ansluta program till Fabric API för GraphQL

  • Artikel

För att ansluta ett program till ett API för GraphQL behöver du tre viktiga uppgifter: ett klient-ID, ditt klient-ID och din GraphQL-slutpunktsadress i Fabric. I följande avsnitt visar vi hur du skapar och hämtar all information du behöver och hur du kommer åt ditt API med hjälp av ett exempelprogram.

Förutsättningar

  • För närvarande kräver API för GraphQL att program använder Microsoft Entra för autentisering. Ditt program måste vara registrerat och konfigurerat på ett lämpligt sätt för att utföra API-anrop mot Fabric. Mer information finns i Skapa en Microsoft Entra-app i Azure.

  • Den autentiserade användare som anropar API:et kräver Kör-behörigheter till GraphQL-API:et (alternativet Kör frågor och mutationer när du lägger till direktåtkomstbehörigheter) och om du använder Enkel sing-on (SSO) som anslutningsalternativ i API:et krävs läs- eller skrivbehörigheter i den datakälla som du väljer i enlighet med detta. Mer information finns i Anslut till en datakälla och skapa ditt schema.

  • Innan du ansluter ett program måste du ha ett API för GraphQL i Fabric. Mer information finns i Skapa ett API för GraphQL i Infrastrukturresurser och lägga till data.

Skapa en Microsoft Entra-app

I följande steg visar vi hur du konfigurerar stöd för ett ReactJS-program i Microsoft Entra.

  1. Registrera ett program med hjälp av stegen som beskrivs i snabbstarten : Registrera ett program med Microsofts identitetsplattform.
  2. Dina ID-värden för Microsoft Entra-appprogram (klient) och katalog-ID (klientorganisation) visas i rutan Sammanfattning. Registrera dessa värden när de krävs senare.
  3. 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 Item.Execute.All-behörigheter. Kontrollera att administratörsmedgivande inte krävs.
  5. Gå tillbaka till listan Hantera och välj Autentisering>Lägg till ett plattformsprogram> med 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 programmet får ett fel som rör begäranden mellan ursprung lägger du till plattformen för mobil- och skrivbordsprogram 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

I det här exemplet skapar vi ett GraphQL-API för att exponera Lakehouse-exempeldata för klienter.

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

  2. I Dataingenjör 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.

    Skärmbild när du väljer alternativet Exempeldata Lakehouse.

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

    Skärmbild av att lägga till Lakehouse-exemplet som GraphQL-datakälla.

  4. Testa GraphQL-API:et i API-redigeraren med hjälp av följande exempelfråga. Det är samma fråga som vi använder i vårt React-klientprogram:

     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.

    Skärmbild av verktygsfältsalternativen för ett API-objekt.

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

    Skärmbild av dialogrutan Kopiera länk som visar var du vill välja Kopiera.

  7. Som klient-IDoch klient-ID från Microsoft Entra-appen registrerades tidigare kopierar du slutpunkts-URI:n efter behov senare.

Konfigurera en React-app för åtkomst till API:et för helgdagar

  1. Vi använder en befintlig React-app som utgångspunkt. Följ alla steg i självstudien Skapa ett React-ensidesprogram och förbered det för autentisering för att skapa ett React-projekt med Microsoft Entra-autentisering som redan har konfigurerats, inklusive ytterligare filer och mappar som krävs för att läggas till i projektstrukturen. Vi behöver bara ändra tre filer för att anpassa appen för vårt GraphQL-användningsfall.

  2. I mappen src öppnar du filen authConfig.js och ersätter innehållet i filen med följande kodfragment:

     /*
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */

 import { LogLevel } from "@azure/msal-browser";

 /**
  * Configuration object to be passed to MSAL instance on creation. 
  * For a full list of MSAL.js configuration parameters, visit:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
  */

 export const graphqlConfig = {
     graphqlEndpoint: "`Enter_the_GraphQL_Endpoint_Here"
 };

 export const msalConfig = {
     auth: {
         clientId: "Enter_the_Application_Id_Here",
         authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
         redirectUri: "http://localhost:3000",
     },
     cache: {
         cacheLocation: "sessionStorage", // This configures where your cache will be stored
         storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
     },
     system: {	
         loggerOptions: {	
             loggerCallback: (level, message, containsPii) => {	
                 if (containsPii) {		
                     return;		
                 }		
                 switch (level) {
                     case LogLevel.Error:
                         console.error(message);
                         return;
                     case LogLevel.Info:
                         console.info(message);
                         return;
                     case LogLevel.Verbose:
                         console.debug(message);
                         return;
                     case LogLevel.Warning:
                         console.warn(message);
                         return;
                     default:
                         return;
                 }	
             }	
         }	
     }
 };

 /**
  * Scopes you add here will be prompted for user consent during sign-in. 
  * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
  * For more information about OIDC scopes, visit: 
  * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
  */
 export const loginRequest = {
     scopes: ["https://analysis.windows.net/powerbi/api/Item.Execute.All"]
 };

 /**
  * Add here the scopes to request when obtaining an access token for MS Graph API. For more information, see:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
  */
 export const graphConfig = {
     graphMeEndpoint: "https://graph.microsoft.com/v1.0/me",
 };

    Som du ser i koden ovan är det viktigt att använda rätt omfång för att få åtkomst till programmet. I vårt fall https://analysis.windows.net/powerbi/api/Item.Execute.All.

    Viktigt!

    Omfång kan ändras under förhandsversionen av Microsoft Fabric API för GraphQL.

  3. Ersätt följande värden med värdena från administrationscentret för Microsoft Entra.

    • clientId - Identifieraren för programmet, även kallad klienten. Ersätt Enter_the_Application_Id_Here med det program-ID-värde (klient) som registrerades tidigare från översiktssidan för det registrerade Microsoft Entra-programmet.
    • authority - Detta består av två delar:
      • Instansen är slutpunkten för molnleverantören. Kontrollera med de olika tillgängliga slutpunkterna i nationella moln.
      • Klientorganisations-ID:t är identifieraren för den klientorganisation där programmet är registrerat. Ersätt Enter_the_Tenant_Info_Here med värdet för katalog-ID (klientorganisation) som registrerades tidigare från översiktssidan för det registrerade programmet.
    • graphQLEndpoint – Fabric-API:et för GraphQL-slutpunkten. Ersätt Enter_the_GraphQL_Endpoint_Here med GraphQL API-slutpunkten som registrerades tidigare.

  4. Spara filen.

  5. I samma src-mapp öppnar du filen App.js och ersätter innehållet i filen med följande kodfragment:

     import React, { useState } from 'react';
 import { PageLayout } from './components/PageLayout';
 import { loginRequest, graphqlConfig } from './authConfig';
 import { ProfileData } from './components/ProfileData';
 import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal } from '@azure/msal-react';
 import './App.css';
 import Button from 'react-bootstrap/Button';
 import Spinner from 'react-bootstrap/Spinner';

 /**
 * Renders information about the signed-in user or a button to retrieve data about the user
 */
 const ProfileContent = () => {
   const { instance, accounts } = useMsal();
   const [graphqlData, setGraphqlData] = useState(null);
   const [display, setDisplay] = useState(false);

   function RequestGraphQL() {
       // Silently acquires an access token which is then attached to a request for GraphQL data
       instance
           .acquireTokenSilent({
               ...loginRequest,
               account: accounts[0],
           })
           .then((response) => {
               callGraphQL(response.accessToken).then((response) => setGraphqlData(response));
           });
   }

 async function callGraphQL(accessToken) {
   setDisplay(true);
   const query = `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
       }
     }
   }`;
   fetch(graphqlConfig.graphqlEndpoint, {
           method: 'POST',
           headers: {
               'Content-Type': 'application/json',
               'Authorization': `Bearer ${accessToken}`,
           },
           body: JSON.stringify({ 
               query: query
           })
       })
       .then((res) => res.json())
       .then((result) => setGraphqlData(result));
 }

   return (
       <>
           <h5 className="card-title">Welcome {accounts[0].name}</h5>
           <br/>
           {graphqlData ? (
               <ProfileData graphqlData={graphqlData} />
           ) : (
               <Button variant="primary" onClick={RequestGraphQL}>
                   Query Fabric API for GraphQL Data 
                   {display ? (
                         <Spinner
                             as="span"
                             animation="border"
                             size="sm"
                             role="status"
                             aria-hidden="true"
                         />
                     ) : null}
               </Button>
           )}
       </>
   );
 };

 /**
 * If a user is authenticated the ProfileContent component above is rendered. Otherwise a message indicating a user is not authenticated is rendered.
 */
 const MainContent = () => {
   return (
       <div className="App">
           <AuthenticatedTemplate>
               <ProfileContent />
           </AuthenticatedTemplate>

           <UnauthenticatedTemplate>
               <h5>
                   <center>
                       Please sign-in to see your profile information.
                   </center>
               </h5>
           </UnauthenticatedTemplate>
       </div>
   );
 };

 export default function App() {
   return (
       <PageLayout>
           <center>
               <MainContent />
           </center>
       </PageLayout>
   );
 }

  6. Spara filen.

  7. Under mappen src/components öppnar du slutligen filen ProfileData.jsx och ersätter innehållet i filen med följande kodfragment:

     import React from "react";
 import ListGroup from 'react-bootstrap/ListGroup'; 
 import Table from 'react-bootstrap/Table';
 /**
  * Renders information about the user obtained from MS Graph 
  * @param props
  */
 export const ProfileData = (props) => {
   const holidays = props.graphqlData.data.publicholidays.items;
   return (
     <Table striped bordered hover responsive>
     <thead>
       <tr>
         <th>Country</th>
         <th>Holiday</th>
         <th>Date</th>
       </tr>
     </thead>
     <tbody>
       {holidays.map((item,i) => (
       <tr key={i}>
         <td>{item.countryOrRegion}</td>
         <td>{item.holidayName}</td>
         <td>{item.date}</td>
       </tr>
       ))}
       </tbody>
     </Table>
 )};

  8. Spara alla filändringar.

  9. I valfritt terminalprogram går du till rotmappen för React-projektet och kör kommandot npm start för att testa programmet lokalt.

  10. När programmet har lästs in i webbläsaren från http://localhost:3000följer du stegen i den sista delen av självstudien Anropa API:et från programmet för att autentisera.

  11. När du har loggat in klickar du på knappen Query Fabric API for GraphQL Data (Fråga infrastrukturresurs-API för GraphQL-data).

    Skärmbild av React-exempelappen efter inloggningen.

  12. En lyckad autentiserad begäran till GraphQL API i Fabric returnerar data från GraphQL-frågan till Lakehouse i vårt React-klientprogram:

    Skärmbild av React-exempelappen när du har tagit emot GraphQL-begäran.

Använda tjänstens huvudnamn

Stegen i föregående avsnitt krävs för att ge åtkomst till användarens huvudnamn, men det är också möjligt att komma åt GraphQL-API:et med tjänstens huvudnamn:

  1. Följ stegen i föregående avsnitt för att skapa en andra Microsoft Entra-app med liknande behörigheter (Item.Execute.All-omfång för PowerBI-tjänsten). I den nya appen lägger du till en klienthemlighet under Certifikat och hemligheter. Mer information finns i Registrera en Microsoft Entra-app och skapa ett huvudnamn för tjänsten.

  2. Kontrollera att klientadministratörer har aktiverat användningen av tjänstens huvudnamn i Infrastrukturresurser. Gå till Klientorganisationsinställningar i administrationsportalen för klientorganisationen. Under Inställningar för utvecklare kan tjänstens huvudnamn använda Infrastruktur-API:er. Med den här inställningen aktiverad visas programmet i Infrastrukturportalen för roll- eller behörighetstilldelning. Du hittar mer information om identitetsstöd.

  3. Tjänstens huvudnamn behöver åtkomst till både GraphQL-API:et och datakällan, mer specifikt Kör behörighet till GraphQL-API:et och läs- eller skrivåtkomst som krävs i valfri datakälla. Öppna arbetsytan i Infrastrukturportalen och välj ellipsen bredvid API:et. Välj Hantera behörigheter för API:et och sedan Lägg till användare. Lägg till programmet och välj Kör frågor och mutationer, vilket ger nödvändiga Kör-behörigheter till tjänstens huvudnamn. I testsyfte är det enklaste sättet att implementera de behörigheter som krävs för både API:et och datakällan genom att lägga till programmet som medlem i arbetsytan med en deltagarroll där både GraphQL-API:et och datakällobjekten finns.

    Skärmbild av GraphQL API-behörigheter.

Viktigt!

När du definierar anslutningsalternativet för ditt API kontrollerar du att API:et är konfigurerat att använda enkel inloggning (SSO). Tjänstens huvudnamn stöder för närvarande inte sparade autentiseringsuppgifter. Mer information finns i Skapa ett API för GraphQL i Infrastrukturresurser och lägga till data

Eftersom tjänstens huvudnamn kräver antingen ett certifikat eller en klienthemlighet stöds det inte av Microsoft Authentication Library (MSAL) i ensidesprogram (SPA) som React-appen som vi skapade i det senaste steget. Du kan använda en serverdelstjänst som är korrekt skyddad med väldefinierad auktoriseringslogik beroende på dina krav och användningsfall.

När api:et har konfigurerats för åtkomst av tjänstens huvudnamn kan du testa det lokalt med hjälp av ett enkelt Node.JS program på den lokala datorn:

const { ClientSecretCredential } = require('@azure/identity');

// Define your Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

const scope = "https://api.fabric.microsoft.com/.default"; // The scope of the token to access Fabric

// Create a credential object with service principal details
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Function to retrieve the token
async function getToken() {
    try {
        // Get the token for the specified scope
        const tokenResponse = await credential.getToken(scope);
        console.log("Access Token:", tokenResponse.token);
    } catch (err) {
        console.error("Error retrieving token:", err.message);
    }
}

När du har installerat beroendena (@azure/identity) med valfri Node.JS pakethanterare, ändrar filen med nödvändig information, sparar och kör den (node <filename.js>) kan du hämta en token från Microsoft Entra.

Token kan sedan användas för att anropa GraphQL-API:et med hjälp av PowerShell genom att ersätta lämplig information med den token som du nyss hämtade, Den GraphQL-fråga som du vill köra och GraphQL API-slutpunkten:

$headers = @{
    Authorization = "Bearer <YOUR_TOKEN>"
    'Content-Type' = 'application/json'
}

$body = @{
    query = @"
    <YOUR_GRAPHQL_QUERY>
"@
}

# Make the POST request to the GraphQL API
$response = Invoke-RestMethod -Uri "<YOUR_GRAPHQL_API_ENDPOINT>" -Method POST -Headers $headers -Body ($body | ConvertTo-Json)

# Output the response
$response | ConvertTo-Json -Depth 10

Du kan också använda cURL för att uppnå samma resultat:

curl -X POST <YOUR_GRAPHQL_API_ENDPOINT> \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"query": "<YOUR_GRAPHQL_QUERY(in a single line)>"}'

I lokala testsyfte kan Node.JS-koden ändras något med ett ytterligare beroende (axios) för att hämta token och anropa API:et i en enda körning:

const { ClientSecretCredential } = require('@azure/identity');
const axios = require('axios');

// Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

// GraphQL API details
const graphqlApiUrl = "YOUR_GRAPHQL_API_ENDPOINT>";
const scope = "https://api.fabric.microsoft.com/.default"; // The scope to request the token for

// The GraphQL query
const graphqlQuery = {
  query: `
  <YOUR_GRAPHQL_QUERY>
  `
};

// Function to retrieve a token and call the GraphQL API
async function fetchGraphQLData() {
  try {
    // Step 1: Retrieve token using the ClientSecretCredential
    const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    const tokenResponse = await credential.getToken(scope);
    const accessToken = tokenResponse.token;

    console.log("Access token retrieved!");

    // Step 2: Use the token to make a POST request to the GraphQL API
    const response = await axios.post(
      graphqlApiUrl,
      graphqlQuery,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Step 3: Output the GraphQL response data
    console.log("GraphQL API response:", JSON.stringify(response.data));
    
  } catch (err) {
    console.error("Error:", err.message);
  }
}

// Execute the function
fetchGraphQLData();

Andra språk

Hitta C#, Python och andra språkexempel för att ansluta till graphQL-API:et på GitHub-lagringsplatsen Microsoft Fabric Samples.

Relaterat innehåll