Jaa

Sovellusten yhdistäminen GraphQL:n Fabric-ohjelmointirajapintaan

  • Artikkeli

Muistiinpano

GraphQL:n Microsoft Fabric -ohjelmointirajapinta on esikatseluvaiheessa.

Jotta voit yhdistää sovelluksen GraphQL:n ohjelmointirajapintaan, tarvitset kolme tärkeää tietoa: asiakastunnuksen, vuokraajatunnuksesi ja GraphQL-päätepisteosoitteesi Fabricissa. Seuraavissa osioissa esitellään, miten voit luoda ja hakea kaikki tarvitsemasi tiedot ja käyttää ohjelmointirajapintaasi mallisovelluksen avulla.

Edellytykset

  • Tällä hetkellä GraphQL-ohjelmointirajapinta edellyttää sovelluksia, jotka käyttävät Microsoft Entraa todentamiseen. Sovellus on rekisteröitävä ja määritettävä riittävästi, jotta se voi suorittaa API-kutsuja Fabricia vastaan. Lisätietoja on artikkelissa Microsoft Entra -sovelluksen luominen Azuressa.

  • Ohjelmointirajapintaa käyttävä todennettu käyttäjä edellyttää Suorita-käyttöoikeuksia GraphQL-ohjelmointirajapinnalle (Suorita kyselyt ja mutaatiot -asetus suoria käyttöoikeuksia lisättäessä). Jos kertakirjautumista (SSO) käytetään ohjelmointirajapinnan yhteysvaihtoehtona, luku- tai kirjoitusoikeudet vaaditaan vastaavasti valitsemassasi tietolähteessä. Lisätietoja on kohdassa Yhdistä tietolähteeseen ja luo rakenne.

  • Ennen kuin yhdistät sovelluksen, sinulla on oltava ohjelmointirajapinta GraphQL:lle Fabricissa. Lisätietoja on artikkelissa Ohjelmointirajapinnan luominen GraphQL:lle Fabricissa ja tietojen lisääminen.

Luo Microsoft Entra -sovellus

Seuraavissa vaiheissa esittelemme, miten voit määrittää ReactJS-sovelluksen tuen Microsoft Entrassa.

  1. Rekisteröi sovellus noudattamalla ohjeita kohdassa Pikaopas: Sovelluksen rekisteröinti Microsoftin käyttäjätietoympäristössä.
  2. Microsoft Entra -sovellussovelluksesi (asiakas) tunnuksen ja hakemiston (vuokraajan) tunnusarvot näkyvät Yhteenveto-ruudussa. Tallenna nämä arvot sellaisina kuin niitä tarvitaan myöhemmin.
  3. Valitse Hallinta -luettelosta -ohjelmointirajapinnan käyttöoikeudetja valitse sitten Lisää käyttöoikeus -.
  4. Lisää PowerBI -palvelu, valitse Delegoidut käyttöoikeudet ja valitse Item.Execute.All permissions. Varmista, ettei järjestelmänvalvojan suostumusta tarvita.
  5. Valitse Hallinta-luettelossa TodennusLisää ympäristö, >Yksisivuinen sovellus.>
  6. Lisää paikallisiin kehitystarkoituksiin kohtaan http://localhost:3000Uudelleenohjauksen URI-osoitteet ja varmista, että sovellus on otettu käyttöön valtuutuskoodin työnkulussa, jossa on Koodin vaihto -ohjelman (PKCE) todisteavain. Tallenna muutoksesi valitsemalla Määritä-painike. Jos sovellus saa useita alkuperää koskeviin pyyntöihin liittyvän virheen, lisää edellisessä vaiheessa mobiili- ja työpöytäsovellusympäristö samalla uudelleenohjauksen URI-uri-kohteella.
  7. Palaa Valtuutus-kohtaan, vieritä alaspäin kohtaan Lisäasetukset ja valitse Salli julkisen asiakkaan työnkulut -kohdassa Kyllä seuraavien mobiili- ja työpöytätyönkulkujen käyttöön ottamiseksi.

GraphQL-mallirajapinnan määrittäminen sovelluksen käyttöä varten

Tässä esimerkissä luomme GraphQL-ohjelmointirajapinnan, joka paljastaa Lakehouse-mallitiedot asiakkaille.

  1. Valitse Fabric-portaalin aloitussivulla Tietotekniikka kuormitusten luettelosta.

  2. Valitse Tietotekniikka-kokemuksessa Käytä mallia ja valitse Lakehouse-kohdasta Julkiset juhlapäivät, jos haluat luoda automaattisesti uuden Lakehousen, jossa on juhlapäivätiedot.

    Näyttökuva mallitietojen Lakehouse-vaihtoehdon valinnasta.

  3. Luo uusi GraphQL-ohjelmointirajapinnan luominen -toiminnon ohjeiden mukaisesti, luo uusi GraphQL-ohjelmointirajapinta ja valitse luomasi Lakehouse. Lisää julkiset juhlapäivät -taulukko, jotta asiakkaat voivat käyttää näitä tietoja.

    Näyttökuva Lakehouse-mallin lisäämisestä GraphQL-tietolähteeksi.

  4. Testaa GraphQL-ohjelmointirajapintaa ohjelmointirajapintaeditorissa käyttämällä seuraavaa esimerkkikyselyä. Käytämme samaa kyselyä React-asiakassovelluksessa:

     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. Valitse Ohjelmointirajapintakohteen työkaluriviltä Kopioi päätepiste .

    Näyttökuva ohjelmointirajapintakohteen työkalurivin vaihtoehdoista.

  6. Valitse Kopioi linkki -näytössä Kopioi.

    Kopioi linkki -valintaikkunan näyttökuva, jossa näkyy, mistä voit valita Kopioi.

  7. Kopioi päätepisteen URI, koska se vaaditaan myöhemmin, kuten Microsoft Entra -sovelluksen asiakastunnus ja vuokraajatunnus on tallennettu aiemmin.

Määritä React-sovellus käyttämään julkisten lomien ohjelmointirajapintaa

  1. Käytämme lähtökohtana olemassa olevaa React-sovellusta. Noudata opetusohjelman kaikkia vaiheita Luo React-yksisivuinen sovellus ja valmistele se todentamista varten, jotta voit luoda React-projektin, jossa Microsoft Entra -todennus on jo määritetty. Tämä sisältää myös lisää tiedostoja ja kansioita, joita projektirakenteeseen täytyy lisätä. Meidän tarvitsee muuttaa vain kolmea tiedostoa, jotta voimme mukauttaa sovelluksen GraphQL-käyttötapausta varten.

  2. Avaa src-kansiossaauthConfig.js-tiedosto ja korvaa tiedoston sisältö seuraavalla koodikatkelmalla:

     /*
  * 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",
 };

    Kuten yllä olevasta koodista näkyy, on tärkeää käyttää oikeaa vaikutusaluetta, jotta voit käyttää sovellusta. Meidän tapauksessamme https://analysis.windows.net/powerbi/api/Item.Execute.All.

    Tärkeä

    Vaikutusalueet saattavat muuttua Microsoft Fabric -ohjelmointirajapinnan GraphQL-esikatselun aikana.

  3. Korvaa seuraavat arvot Microsoft Entra -hallintakeskuksen arvoilla.

    • clientId - Sovelluksen tunniste, jota kutsutaan myös asiakkaaksi. Korvaa Enter_the_Application_Id_Here Sovellus (asiakas) -tunnuksen arvolla, joka tallennettiin aiemmin rekisteröidyn Microsoft Entra -sovelluksen Yleiskatsaus-sivulta.
    • authority - Se koostuu kahdesta osasta:
      • Esiintymä on pilvipalveluntarjoajan päätepiste. Tarkista kansallisissa pilvipalveluissa käytettävissä olevat eri päätepisteet.
      • Vuokraajatunnus on sen vuokraajan tunnus, johon sovellus on rekisteröity. Korvaa Enter_the_Tenant_Info_Here rekisteröidyn sovelluksen Yleiskatsaus-sivulla tallennetulla Hakemiston (vuokraajan) tunnuksen arvolla.
    • graphQLEndpoint - Fabric-ohjelmointirajapinta GraphQL-päätepisteelle. Korvaa Enter_the_GraphQL_Endpoint_Here aiemmin kirjatulla GraphQL-ohjelmointirajapinnan päätepisteellä.

  4. Tallenna tiedosto.

  5. Avaa samassa src-kansiossa App.js-tiedosto ja korvaa tiedoston sisältö seuraavalla koodikatkelmalla:

     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. Tallenna tiedosto.

  7. Avaa lopuksi src/components-kansiossa ProfileData.jsx-tiedosto ja korvaa tiedoston sisältö seuraavalla koodikatkelmalla:

     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. Tallenna kaikki tiedoston muutokset.

  9. Siirry valitsemassasi päätesovelluksessa React-projektin pääkansioon ja suorita komento npm start sovelluksen testaamiseksi paikallisesti.

  10. Kun sovellus latautuu selaimessasi kohteesta http://localhost:3000, suorita opetusohjelman viimeisen osan vaiheet Kutsu ohjelmointirajapinta sovelluksesta -todennusta varten.

  11. Kun olet kirjautunut sisään, napsauta painiketta Query Fabric -ohjelmointirajapinta GraphQL-tiedoille.

Näyttökuva React-mallisovelluksesta sisäänkirjautumisen jälkeen.

  1. Onnistunut todennettu pyyntö Fabricin GraphQL-ohjelmointirajapinnalle palauttaa tiedot GraphQL-kyselystä Lakehouseen React-asiakassovelluksessamme:

    Näyttökuva React-mallisovelluksesta GraphQL-pyynnön vastaanottamisen jälkeen.

Palvelun päänimen käyttäminen

Edellisen osion vaiheita tarvitaan käyttäjäobjektien käyttöoikeuksien antamiseen, mutta voit myös käyttää GraphQL-ohjelmointirajapintaa palvelun päänimellä:

  1. Luo toinen Microsoft Entra -sovellus, jolla on samanlaiset käyttöoikeudet (Item.Execute.All-vaikutusalue PowerBI-palvelussa) noudattamalla edellisen osion ohjeita. Lisää uuteen sovellukseen asiakassalaisuus kohdasta Varmenteet ja salaiset koodit. Lisätietoja on artikkelissa Microsoft Entra -sovelluksen rekisteröiminen ja palvelun päänimen luominen.

  2. Varmista, että vuokraajan järjestelmänvalvojat ovat mahdollistaneet palvelun päänimien käytön Fabricissa. Siirry vuokraajan hallintaportaalissa vuokraaja-asetuksiin. Ota Kehittäjäasetukset-kohdassa käyttöön palvelun päänimet voivat käyttää Fabric-ohjelmointirajapintoja. Kun tämä asetus on käytössä, sovellus näkyy Fabric-portaalissa rooli- tai käyttöoikeusmäärityksessä. Lisätietoja käyttäjätietojen tuesta.

  3. Palvelun päänimi tarvitsee käyttöoikeuden sekä GraphQL-ohjelmointirajapintaan että tietolähteeseen, tarkemmin Sanottuna Suorita käyttöoikeus GraphQL-ohjelmointirajapintaan ja luku- tai kirjoitusoikeudet, joita tarvitaan valitsemassasi tietolähteessä vastaavasti. Avaa työtila Fabric-portaalissa ja valitse kolme pistettä ohjelmointirajapinnan vierestä. Valitse ohjelmointirajapinnan käyttöoikeuksien hallinta ja sitten Lisää käyttäjä. Lisää sovellus ja valitse Suorita kyselyt ja mutaatiot, jolloin saat tarvittavat Suoritus-käyttöoikeudet palvelun päänimeen. Testausta varten helpoin tapa toteuttaa vaaditut käyttöoikeudet sekä ohjelmointirajapinnalle että tietolähteelle on lisätä sovellus työtilan jäseneksi, jolla on osallistujarooli, jossa sekä GraphQL-ohjelmointirajapinta että tietolähdekohteet sijaitsevat.

    Näyttökuva GraphQL-ohjelmointirajapinnan käyttöoikeuksista.

Tärkeä

Kun määrität ohjelmointirajapinnan yhteysasetusta, varmista, että ohjelmointirajapinta on määritetty käyttämään kertakirjautumista (SSO). Tällä hetkellä palvelun päänimet eivät tue tallennettuja tunnistetietoja. Lisätietoja on artikkelissa Ohjelmointirajapinnan luominen GraphQL:lle Fabricissa ja tietojen lisääminen

Koska palvelun päänimi vaatii joko varmenteen tai asiakassalaisuuden, Microsoftin todentamiskirjasto (MSAL) ei tue sitä yhden sivun sovelluksissa (SPA: t), kuten edellisessä vaiheessa luomamme React-sovellus. Voit hyödyntää taustapalvelua, joka on suojattu oikein määritellyllä valtuutuslogiikalla tarpeidesi ja käyttötapausten mukaan.

Kun palvelun päänimi on määritetty käyttämään ohjelmointirajapintaa, voit testata sitä paikallisesti käyttämällä yksinkertaista Node.JS paikallisessa tietokoneessa:

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);
    }
}

Kun olet asentanut riippuvuudet (@azure/identity) valitsemaasi Node.JS paketinhallintaan, muokannut tiedostoa tarvittavilla tiedoilla, tallentanut ja suorittanut sen (node <filename.js>), voit noutaa tunnuksen Microsoft Entrasta.

Tunnuksen avulla voidaan käynnistää GraphQL-ohjelmointirajapinta PowerShellin avulla korvaamalla tarvittavat tiedot juuri noutamallasi tunnuuksella, suoritettavalla GraphQL-kyselyllä ja GraphQL-ohjelmointirajapinnan päätepisteellä:

$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

Voit myös käyttää cURL:ää saman tuloksen saavuttamiseksi:

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)>"}'

Paikallisessa testauksessa Node.JS koodia voidaan hieman muokata lisäriippuvuudella (axios), jotta se voi noutaa tunnuksen ja käynnistää ohjelmointirajapinnan yksittäisessä suorituksessa:

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();

Muut kielet

Etsi C#, Python ja muita kielimalleja, joiden avulla voit muodostaa yhteyden GraphQL-ohjelmointirajapintaasi , Microsoft Fabric Samples GitHub -säilöstä.

Liittyvä sisältö