Menyambungkan aplikasi ke Fabric API untuk GraphQL

Artikel
10/25/2024

Catatan

Microsoft Fabric API untuk GraphQL sedang dalam pratinjau.

Untuk menyambungkan aplikasi ke API untuk GraphQL, Anda memerlukan tiga informasi penting: ID Klien, ID Penyewa Anda, dan alamat titik akhir GraphQL Anda di Fabric. Di bagian berikut, kami menampilkan cara membuat dan mengambil semua detail yang Anda butuhkan dan cara mengakses API Anda menggunakan aplikasi sampel.

Prasyarat

Saat ini API untuk GraphQL mengharuskan aplikasi menggunakan Microsoft Entra untuk autentikasi. Aplikasi Anda perlu didaftarkan dan dikonfigurasi secara memadai untuk melakukan panggilan API terhadap Fabric. Untuk informasi selengkapnya, lihat Membuat aplikasi Microsoft Entra di Azure.
Pengguna terautentikasi yang memanggil API harus menjadi anggota ruang kerja tempat API dan item sumber data berada dengan peran Kontributor. Untuk informasi selengkapnya, lihat Memberi pengguna akses ke ruang kerja.
Sebelum menghubungkan aplikasi, Anda harus memiliki API untuk GraphQL di Fabric. Untuk informasi selengkapnya, lihat Membuat API untuk GraphQL di Fabric dan menambahkan data.

Membuat aplikasi Microsoft Entra

Dalam langkah-langkah berikut, kami menampilkan cara mengonfigurasi dukungan untuk aplikasi ReactJS di Microsoft Entra.

Masuk ke portal Azure.
Mencari dan memilih Microsoft Entra ID.
Dari daftar Kelola , pilih Pendaftaran aplikasi.
Pilih Pendaftaran baru.
Isi informasi yang diperlukan:
- Nama - Masukkan nama untuk aplikasi Anda.
- Jenis akun yang didukung - Pilih akun yang Anda inginkan untuk didukung aplikasi Anda.
- (Opsional) URI Pengalihan - Masukkan URI jika diperlukan. GraphQL.Execute.All atau Item.Execute.All
Pilih Daftarkan. Id Aplikasi Microsoft Entra (klien) dan nilai ID Direktori (penyewa) Anda ditampilkan dalam kotak Ringkasan. Rekam nilai-nilai ini saat diperlukan nanti.
Dari daftar Kelola , pilih Izin API, lalu Tambahkan izin.
Tambahkan Layanan PowerBI, pilih Izin yang didelegasikan, dan pilih izin , dan Datamart.ReadWrite.All. Pastikan persetujuan Admin tidak diperlukan.
Kembali ke daftar Kelola , pilih Autentikasi, pilih Tambahkan platform, lalu pilih Aplikasi halaman tunggal.
Untuk tujuan pengembangan lokal, tambahkan http://localhost:3000 di bawah URI Pengalihan dan konfirmasikan aplikasi diaktifkan untuk alur kode otorisasi dengan Proof Key for Code Exchange (PKCE). Pilih tombol Konfigurasi untuk menyimpan perubahan Anda. Jika aplikasi menerima kesalahan yang terkait dengan permintaan lintas asal, tambahkan platform Aplikasi seluler dan desktop di langkah sebelumnya dengan URI pengalihan yang sama.
Kembali ke Otorisasi, gulir ke bawah ke Pengaturan Tingkat Lanjut dan, di bawah Izinkan alur klien publik, pilih Ya untuk Mengaktifkan alur seluler dan desktop berikut.

Menyiapkan sampel GraphQL API untuk akses aplikasi

Dalam contoh ini, kami membuat API GraphQL untuk mengekspos data Lakehouse sampel ke klien.

Dari beranda portal Fabric, pilih Rekayasa Data dari daftar beban kerja.
Dalam pengalaman Rekayasa Data, pilih Gunakan sampel dan, di bawah Lakehouse, pilih Hari libur umum untuk membuat Lakehouse baru secara otomatis dengan data hari libur umum.
Mengikuti langkah-langkah dari Buat API untuk GraphQL, buat API GraphQL baru dan pilih Lakehouse yang Anda buat. Tambahkan tabel hari libur nasional untuk memungkinkan klien mengakses data ini.

Uji API GraphQL di editor API menggunakan kueri sampel berikut. Ini adalah kueri yang sama dengan yang kami gunakan dalam aplikasi klien React kami:

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

Pilih Salin titik akhir pada toolbar item API.
Di layar Salin tautan, pilih Salin.
Sebagai ID Klien dan ID Penyewa dari aplikasi Microsoft Entra yang direkam sebelumnya, salin URI titik akhir seperti yang diperlukan nanti.

Mengonfigurasi aplikasi React untuk mengakses API hari libur umum

Kami menggunakan aplikasi React yang ada sebagai titik awal. Ikuti semua langkah pada tutorial Membuat aplikasi satu halaman React dan menyiapkannya untuk autentikasi untuk membuat proyek React dengan autentikasi Microsoft Entra yang sudah dikonfigurasi, termasuk file dan folder tambahan yang diperlukan untuk ditambahkan ke struktur proyek. Kami hanya perlu mengubah tiga file untuk menyesuaikan aplikasi untuk kasus penggunaan GraphQL kami.

Di folder src, buka file authConfig.js dan ganti konten file dengan cuplikan kode berikut:

 /*
  * 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","https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.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",
 };

Seperti yang Anda lihat dalam kode di atas, penting untuk menggunakan cakupan yang benar untuk mengakses aplikasi. Dalam kasus https://analysis.windows.net/powerbi/api/Item.Execute.All kami dan https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All.

Penting

Cakupan mungkin berubah selama Microsoft Fabric API untuk pratinjau GraphQL.

Ganti nilai berikut dengan nilai dari pusat admin Microsoft Entra.
- clientId - Pengidentifikasi aplikasi, juga disebut sebagai klien. Ganti Enter_the_Application_Id_Here dengan nilai ID Aplikasi (klien) yang direkam sebelumnya dari halaman gambaran umum aplikasi Microsoft Entra terdaftar.
- authority - Ini terdiri dari dua bagian:
  - Instans adalah titik akhir penyedia cloud. Periksa dengan berbagai titik akhir yang tersedia di cloud Nasional.
  - ID Penyewa adalah pengidentifikasi penyewa tempat aplikasi terdaftar. Ganti Enter_the_Tenant_Info_Here dengan nilai ID Direktori (penyewa) yang direkam sebelumnya dari halaman gambaran umum aplikasi terdaftar.
- graphQLEndpoint - FABRIC API untuk titik akhir GraphQL. Ganti Enter_the_GraphQL_Endpoint_Here dengan titik akhir GraphQL API yang direkam sebelumnya.
Simpan file.

Di folder src yang sama, buka file App.js dan ganti konten file dengan cuplikan kode berikut:

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

Simpan file.

Terakhir, di bawah folder src/components , buka file ProfileData.jsx dan ganti konten file dengan cuplikan kode berikut:

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

Simpan semua perubahan file.
Dalam aplikasi terminal pilihan Anda, buka folder akar proyek React dan jalankan perintah npm start untuk menguji aplikasi secara lokal.
Setelah aplikasi dimuat di browser Anda dari http://localhost:3000, ikuti langkah-langkah pada bagian terakhir tutorial Panggil API dari aplikasi untuk mengautentikasi.
Setelah masuk, klik tombol Query Fabric API untuk Data GraphQL.
Permintaan terautentikasi yang berhasil ke API GraphQL di Fabric mengembalikan data dari kueri GraphQL ke Lakehouse di aplikasi klien React kami:

Menggunakan perwakilan layanan

Meskipun langkah-langkah di bagian sebelumnya diperlukan untuk menyediakan akses ke prinsipal pengguna, anda juga dapat mengakses API GraphQL dengan perwakilan layanan:

Ikuti langkah-langkah di bagian sebelumnya untuk membuat aplikasi Microsoft Entra kedua. Di aplikasi baru, tambahkan rahasia klien di bawah Sertifikat dan Rahasia, untuk informasi selengkapnya lihat Mendaftarkan aplikasi Microsoft Entra dan membuat perwakilan layanan.
Di portal Admin Penyewa, buka Pengaturan Penyewa. Di bawah Pengaturan Pengembang, aktifkan Perwakilan Layanan dapat menggunakan FABRIC API. Dengan mengaktifkan pengaturan ini, aplikasi akan terlihat di Portal Fabric untuk penetapan peran atau izin. Anda dapat menemukan informasi selengkapnya tentang dukungan Identitas.
Perwakilan layanan akan memerlukan akses ke API GraphQL dan sumber data. Di Portal Fabric, tambahkan aplikasi sebagai anggota ruang kerja dengan peran kontributor tempat API GraphQL dan item sumber data berada.

Karena Perwakilan Layanan memerlukan sertifikat atau rahasia klien, sertifikat tersebut tidak didukung oleh Microsoft Authentication Library (MSAL) dalam aplikasi halaman tunggal (SPAs) seperti aplikasi React yang kami buat di langkah terakhir. Anda dapat memanfaatkan layanan backend yang diamankan dengan benar dengan logika otorisasi yang ditentukan dengan baik tergantung pada kebutuhan dan kasus penggunaan Anda.

Setelah API Anda dikonfigurasi untuk diakses oleh Perwakilan Layanan, Anda dapat mengujinya secara lokal menggunakan aplikasi Node.JS sederhana di komputer lokal Anda:

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

Setelah menginstal dependensi (@azure/identity) dengan pengelola paket pilihan Node.JS Anda, memodifikasi file dengan informasi yang diperlukan, menyimpan dan mengeksekusinya (node <filename.js>), Anda akan dapat mengambil token dari Microsoft Entra.

Token kemudian dapat digunakan untuk memanggil API GraphQL Anda menggunakan PowerShell dengan mengganti detail yang sesuai dengan token yang baru saja Anda ambil, kueri GraphQL yang ingin Anda jalankan, dan Titik Akhir API GraphQL:

$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

Atau, Anda dapat menggunakan cURL untuk mencapai hasil yang sama:

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

Untuk tujuan pengujian lokal, kode Node.JS dapat sedikit dimodifikasi dengan dependensi tambahan (axios) untuk mengambil token dan memanggil API dalam satu eksekusi:

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

Bahasa lainnya

Temukan C#, Python, dan sampel bahasa lain untuk menyambungkan ke API GraphQL Anda di repositori GitHub Sampel Microsoft Fabric.

Bagikan melalui

Menyambungkan aplikasi ke Fabric API untuk GraphQL

Prasyarat

Membuat aplikasi Microsoft Entra

Menyiapkan sampel GraphQL API untuk akses aplikasi

Mengonfigurasi aplikasi React untuk mengakses API hari libur umum

Menggunakan perwakilan layanan

Bahasa lainnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Menyambungkan aplikasi ke Fabric API untuk GraphQL

Prasyarat

Membuat aplikasi Microsoft Entra

Menyiapkan sampel GraphQL API untuk akses aplikasi

Mengonfigurasi aplikasi React untuk mengakses API hari libur umum

Menggunakan perwakilan layanan

Bahasa lainnya

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: