เชื่อมต่อแอปพลิเคชันกับ Fabric API สําหรับ GraphQL
หมายเหตุ
Microsoft Fabric API สําหรับ GraphQL อยู่ในตัวอย่าง
เพื่อเชื่อมต่อแอปพลิเคชันกับ API สําหรับ GraphQL คุณจําเป็นต้องมีสามส่วนของข้อมูลที่สําคัญ: ID ไคลเอ็นต์ ID ผู้เช่าของคุณ และที่อยู่ปลายทาง GraphQL ของคุณใน Fabric ในส่วนต่อไปนี้ เราจะแสดงวิธีการสร้างและเรียกดูรายละเอียดทั้งหมดที่คุณต้องการ และวิธีการเข้าถึง API ของคุณโดยใช้แอปพลิเคชันตัวอย่าง
ข้อกำหนดเบื้องต้น
API สําหรับ GraphQL ในขณะนี้จําเป็นต้องใช้ Microsoft Entra สําหรับการรับรองความถูกต้อง แอปพลิเคชันของคุณต้องลงทะเบียน และกําหนดค่าอย่างเพียงพอเพื่อดําเนินการเรียกใช้ API กับ Fabric สําหรับข้อมูลเพิ่มเติม ดูสร้างแอป Microsoft Entra ใน Azure
ผู้ใช้ที่ได้รับการรับรองความถูกต้องที่เรียกใช้ API จําเป็นต้องเป็นสมาชิกของพื้นที่ทํางานที่ทั้ง API และรายการแหล่งข้อมูลมีบทบาทผู้สนับสนุนอยู่ สําหรับข้อมูลเพิ่มเติม ให้ดู ให้ผู้ใช้สามารถเข้าถึงพื้นที่ทํางาน
ก่อนที่คุณจะเชื่อมต่อแอปพลิเคชัน คุณต้องมี API สําหรับ GraphQL ใน Fabric สําหรับข้อมูลเพิ่มเติม ดูสร้าง API สําหรับ GraphQL ใน Fabric และเพิ่มข้อมูล
สร้างแอป Microsoft Entra
ในขั้นตอนต่อไปนี้ เราจะแสดงวิธีการกําหนดค่าการสนับสนุนสําหรับแอปพลิเคชัน ReactJS ใน Microsoft Entra
ลงชื่อเข้าใช้ พอร์ทัล Azure
ค้นหาและเลือก รหัส Microsoft Entra
จากรายการ จัดการ ให้เลือก การลงทะเบียนแอป
เลือก การลงทะเบียนใหม่
กรอกข้อมูลที่จําเป็น:
ชื่อ - ป้อนชื่อสําหรับแอปพลิเคชันของคุณ
ประเภท บัญชีที่รองรับ - เลือกบัญชีที่คุณต้องการให้แอปของคุณสนับสนุน
(ไม่บังคับ) เปลี่ยนเส้นทาง URI - ใส่ URI ถ้าจําเป็น GraphQL.Execute.All หรือ Item.Execute.All
เลือก การลงทะเบียน ID แอปพลิเคชัน (ไคลเอนต์) ของแอป Microsoft Entra และค่า ID ไดเรกทอรี (ผู้เช่า) ของคุณจะแสดงในกล่องสรุป บันทึกค่าเหล่านี้ตามที่จําเป็นต้องมีในภายหลัง
จากรายการจัดการ เลือกสิทธิ์ API จากนั้นเพิ่มสิทธิ์
เพิ่มบริการ PowerBI เลือก สิทธิ์ที่ได้รับมอบ และเลือก และ สิทธิ์ Datamart.ReadWrite.All ตรวจสอบให้แน่ใจว่าไม่จําเป็นต้องได้รับความยินยอมจากผู้ดูแลระบบ
กลับไปที่รายการ จัดการ เลือก การรับรองความถูกต้อง เลือก เพิ่มแพลตฟอร์ม จากนั้นเลือก แอปพลิเคชันหน้าเดียว
สําหรับการพัฒนาภายในเครื่อง ให้เพิ่ม
http://localhost:3000
ภายใต้การเปลี่ยนเส้นทาง URI และยืนยันว่าแอปพลิเคชันเปิดใช้งานสําหรับโฟลว์รหัสการให้สิทธิ์ที่มี Proof Key สําหรับ Code Exchange (PKCE) เลือก ปุ่ม กําหนดค่า เพื่อบันทึกการเปลี่ยนแปลงของคุณ ในกรณีที่แอปพลิเคชันได้รับข้อผิดพลาดที่เกี่ยวข้องกับคําขอข้ามแหล่งที่มา ให้เพิ่ม แพลตฟอร์มแอปพลิเคชัน สําหรับอุปกรณ์เคลื่อนที่และเดสก์ท็อปในขั้นตอนก่อนหน้าด้วย URI เปลี่ยนเส้นทางเดียวกันกลับไปที่ การอนุญาต เลื่อนลงไปที่ การตั้งค่าขั้นสูง และภายใต้ อนุญาตโฟลว์ไคลเอ็นต์สาธารณะ เลือก ใช่ สําหรับ เปิดใช้งานโฟลว์อุปกรณ์เคลื่อนที่และเดสก์ท็อปต่อไปนี้
ตั้งค่าตัวอย่าง GraphQL API สําหรับการเข้าถึงแอปพลิเคชัน
ในตัวอย่างนี้ เราสร้าง GraphQL API เพื่อเปิดเผยข้อมูลตัวอย่างของเลคเฮ้าส์ไปยังไคลเอ็นต์
จากโฮมเพจพอร์ทัล Fabric เลือกวิศวกรข้อมูลจากรายการของปริมาณงาน
ในประสบการณ์วิศวกรข้อมูลให้เลือก ใช้ตัวอย่าง และภายใต้เลคเฮ้าส์ ให้เลือก วันหยุดราชการ เพื่อสร้างเลคเฮ้าส์ใหม่โดยอัตโนมัติด้วยข้อมูลวันหยุดราชการ
ทําตามขั้นตอนจาก สร้าง API สําหรับ GraphQL สร้าง GraphQL API ใหม่และเลือกเลคเฮ้าส์ที่คุณสร้างขึ้น เพิ่มตารางวันหยุดราชการเพื่อให้ไคลเอ็นต์เข้าถึงข้อมูลนี้
ทดสอบ GraphQL API ในตัว แก้ไข API โดยใช้คิวรีตัวอย่างต่อไปนี้ ซึ่งเป็นคิวรีเดียวกับที่เราใช้ในแอปพลิเคชันไคลเอ็นต์ React ของเรา:
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 } } }
เลือก คัดลอกจุด สิ้นสุด บนแถบเครื่องมือของรายการ API
ในหน้าจอ คัดลอกลิงก์ เลือก คัดลอก
ในฐานะ ID ไคลเอ็นต์และ ID ผู้เช่าจากแอป Microsoft Entra ที่บันทึกไว้ก่อนหน้านี้ ให้คัดลอก URI ของจุดสิ้นสุดตามที่จําเป็นต้องใช้ในภายหลัง
กําหนดค่าแอป React เพื่อเข้าถึง API วันหยุดราชการ
เราใช้แอป React ที่มีอยู่เป็นจุดเริ่มต้น ทําตามขั้นตอนทั้งหมดในบทช่วยสอน สร้างแอปพลิเคชันแบบหน้าเดียวของ React และเตรียมพร้อมสําหรับการรับรองความถูกต้อง เพื่อสร้างโครงการ React ที่มีการกําหนดค่าการรับรองความถูกต้อง Microsoft Entra ไว้แล้ว รวมถึงไฟล์และโฟลเดอร์เพิ่มเติมที่จําเป็นต้องเพิ่มลงในโครงสร้างโครงการ เราเพียงแค่เปลี่ยนไฟล์สามไฟล์เพื่อปรับแอปสําหรับกรณีการใช้งาน GraphQL ของเรา
ใน โฟลเดอร์ src เปิด ไฟล์ authConfig.js และแทนที่เนื้อหาของไฟล์ด้วยส่วนย่อยของโค้ดต่อไปนี้:
/* * 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", };
ตามที่คุณเห็นในรหัสด้านบน สิ่งสําคัญคือต้องใช้ขอบเขตที่ถูกต้องเพื่อเข้าถึงแอปพลิเคชัน ในกรณี
https://analysis.windows.net/powerbi/api/Item.Execute.All
ของเรา และhttps://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All
สำคัญ
ขอบเขตอาจเปลี่ยนแปลงในระหว่างการ Microsoft Fabric API สําหรับการแสดงตัวอย่าง GraphQL
แทนที่ค่าต่อไปนี้ด้วยค่าจากศูนย์การจัดการ Microsoft Entra
clientId
- ตัวระบุของแอปพลิเคชัน หรือที่เรียกว่าไคลเอ็นต์ แทนที่Enter_the_Application_Id_Here
ด้วย ค่า ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ถูกบันทึกไว้ก่อนหน้านี้จากหน้าภาพรวมของแอปพลิเคชัน Microsoft Entra ที่ลงทะเบียนไว้authority
-นี้ประกอบด้วยสองส่วน:- อินสแตนซ์คือจุดสิ้นสุดของผู้ให้บริการระบบคลาวด์ ตรวจสอบด้วยจุดสิ้นสุดที่พร้อมใช้งานที่แตกต่างกันในระบบ คลาวด์แห่งชาติ
- รหัสผู้เช่าเป็นตัวระบุของผู้เช่าที่มีการลงทะเบียนแอปพลิเคชัน แทนที่ Enter_the_Tenant_Info_Here ด้วย ค่า ID ไดเรกทอรี (ผู้เช่า) ที่ถูกบันทึกไว้ก่อนหน้านี้จากหน้าภาพรวมของแอปพลิเคชันที่ลงทะเบียนไว้
graphQLEndpoint
- Fabric API สําหรับจุดสิ้นสุด GraphQL แทนที่Enter_the_GraphQL_Endpoint_Here
ด้วยจุดสิ้นสุด GraphQL API ที่บันทึกไว้ก่อนหน้านี้
บันทึกไฟล์
ในโฟลเดอร์ src เดียวกัน เปิดไฟล์ App.js และแทนที่เนื้อหาของไฟล์ด้วยส่วนย่อยของโค้ดต่อไปนี้:
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> ); }
บันทึกไฟล์
สุดท้าย ภายใต้ โฟลเดอร์ src/components เปิด ไฟล์ ProfileData.jsx และแทนที่เนื้อหาของไฟล์ด้วยส่วนย่อยของโค้ดต่อไปนี้:
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> )};
บันทึกการเปลี่ยนแปลงของไฟล์ทั้งหมด
ในแอปพลิเคชันเทอร์มินัลที่คุณเลือกให้ไปที่โฟลเดอร์รากของโครงการ React และดําเนินการคําสั่ง
npm start
เพื่อทดสอบแอปพลิเคชันภายในเครื่องเมื่อแอปพลิเคชันโหลดในเบราว์เซอร์ของคุณจาก
http://localhost:3000
ทําตามขั้นตอนในส่วนสุดท้ายของบทช่วยสอน เรียกใช้ API จากแอปพลิเคชัน เพื่อรับรองความถูกต้องหลังจากลงชื่อเข้าใช้แล้ว ให้คลิกที่ปุ่ม Query Fabric API สําหรับข้อมูล GraphQL
คําขอการรับรองความถูกต้องที่สําเร็จไปยัง GraphQL API ใน Fabric จะส่งกลับข้อมูลจากคิวรี GraphQL ไปยัง Lakehouse ในแอปพลิเคชันไคลเอ็นต์ React ของเรา:
ใช้โครงร่างสําคัญของบริการ
แม้ว่าขั้นตอนในส่วนก่อนหน้านี้จะต้องให้สิทธิ์การเข้าถึงหลักของผู้ใช้ แต่ก็สามารถเข้าถึง GraphQL API ด้วยบริการหลักได้:
- ทําตามขั้นตอนในส่วนก่อนหน้าเพื่อสร้างแอป Microsoft Entra ที่สอง ในแอปใหม่ เพิ่มความลับของไคลเอ็นต์ภายใต้ ใบรับรองและข้อมูลลับ สําหรับข้อมูลเพิ่มเติม ดูลงทะเบียนแอป Microsoft Entra และสร้างบริการหลัก
- ในพอร์ทัลผู้ดูแลระบบผู้เช่า ไปที่ การตั้งค่าผู้เช่า ภายใต้การตั้งค่านักพัฒนา เปิดใช้งานบริการหลักสามารถใช้ Fabric API ได้ เมื่อเปิดใช้งานการตั้งค่านี้ แอปพลิเคชันจะปรากฏใน Fabric Portal สําหรับบทบาทหรือการกําหนดสิทธิ์ คุณสามารถหาข้อมูลเพิ่มเติมได้ที่ การสนับสนุนข้อมูลประจําตัว
- บริการหลักจะต้องเข้าถึงทั้ง GraphQL API และแหล่งข้อมูล ใน Fabric Portal ให้เพิ่มแอปพลิเคชันเป็นสมาชิกพื้นที่ทํางานที่มีบทบาทผู้สนับสนุนที่มีทั้ง GraphQL API และรายการแหล่งข้อมูลอยู่
เนื่องจากองค์ประกอบหลักของบริการต้องการใบรับรองหรือข้อมูลลับของไคลเอ็นต์ จึงไม่ได้รับการสนับสนุนโดยไลบรารีการรับรองความถูกต้องของ Microsoft (MSAL) ในแอปพลิเคชันหน้าเดียว (SPAs) เช่น แอป React ที่เราสร้างขึ้นในขั้นตอนสุดท้าย คุณสามารถใช้ประโยชน์จากบริการ Backend ได้อย่างถูกต้องด้วยตรรกะการรับรองความถูกต้องที่กําหนดไว้อย่างดีโดยขึ้นอยู่กับความต้องการและกรณีการใช้งานของคุณ
เมื่อ API ของคุณได้รับการกําหนดค่าให้สามารถเข้าถึงได้โดยโครงร่างสําคัญของบริการ คุณสามารถทดสอบภายในเครื่องโดยใช้แอปพลิเคชัน Node.JS อย่างง่ายในเครื่องภายในของคุณ:
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);
}
}
หลังจากติดตั้งการขึ้นต่อกัน (@azure/identity
) ด้วยตัวจัดการแพคเกจ Node.JS แบบที่คุณเลือกให้ปรับเปลี่ยนไฟล์ด้วยข้อมูลที่จําเป็นบันทึกและดําเนินการ (node <filename.js>
) คุณจะสามารถเรียกใช้โทเค็นจาก Microsoft Entra ได้
โทเค็นสามารถใช้เพื่อเรียกใช้ GraphQL API ของคุณโดยใช้ PowerShell โดยการแทนที่รายละเอียดที่เหมาะสมด้วย โทเค็น ที่คุณเพิ่งเรียกใช้ คิวรี GraphQL ที่คุณต้องการดําเนินการ และ จุดสิ้นสุด GraphQL API:
$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
อีกวิธีหนึ่งคือ คุณสามารถใช้ cURL เพื่อให้ได้ผลลัพธ์เดียวกัน:
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)>"}'
สําหรับวัตถุประสงค์ในการทดสอบภายในเครื่อง รหัส Node.JS สามารถปรับเปลี่ยนเล็กน้อยด้วยการขึ้นต่อกันเพิ่มเติม (axios
) เพื่อเรียกใช้โทเค็นและเรียกใช้ API ในการดําเนินการเดียว:
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();
ภาษาอื่น ๆ
ค้นหา C#, Python และตัวอย่างภาษาอื่น ๆ สําหรับการเชื่อมต่อกับ GraphQL API ของคุณใน ที่เก็บ Microsoft Fabric Samples GitHub