이 빠른 시작에서는 Fabric 포함을 사용하여 브라우저 기반 JavaScript 또는 TypeScript 웹앱에 Microsoft Fabric Real-Time 대시보드를 추가합니다. Fabric 포함을 사용하면 사용자가 Microsoft Entra ID ID 및 위임된 권한을 사용하여 액세스하는 동안 앱에서 대시보드를 표시할 수 있습니다.
앱은 JavaScript용 Microsoft 인증 라이브러리(MSAL.js)를 사용하여 Microsoft Fabric API 리소스에 대한 위임된 액세스 토큰을 요청하고 Fabric Embed SDK를 사용하여 대시보드를 렌더링합니다. 완료되면 앱은 사용자를 Fabric 포털로 보내지 않고 Real-Time 대시보드를 표시합니다.
Real-Time 대시보드를 포함하기 위한 필수 구성 요소
시작하기 전에 Microsoft Fabric 포함에 대한 환경 설정을 완료합니다. 이 설정은 이 빠른 시작에서 사용하는 Microsoft Entra 앱 등록, 위임된 권한, Microsoft Fabric 작업 영역, 활성 Fabric 용량 및 대시보드 값을 만들거나 확인합니다.
다음 값과 권한도 필요합니다.
| 요구 사항 | Description |
|---|---|
| 웹앱 프로젝트 | npm을 사용하는 브라우저 기반 JavaScript 또는 TypeScript 앱입니다. 이 빠른 시작 가이드의 임베드 코드는 클라이언트 측에서 실행됩니다. |
| 앱 등록 클라이언트 ID Microsoft Entra | MSAL.js사용하여 사용자를 로그인하는 앱 등록의 클라이언트 ID입니다. |
| Microsoft Entra 테넌트 ID | 앱 등록 및 Fabric 사용자가 구성되는 테넌트 ID입니다. |
| 위임된 API 권한 |
Fabric.Embed 및 Item.Read.All에 대한 위임된 동의. MSAL 토큰 요청은 Fabric .default 범위를 사용하여 이러한 동의된 권한을 요청합니다. |
| 작업 영역 ID | Real-Time Dashboard를 포함하고 활성 상태인 Fabric 용량에 할당된 Microsoft Fabric 작업 영역 ID입니다. |
| Real-Time 대시보드 항목 ID | 포함하려는 Real-Time 대시보드의 Microsoft Fabric 항목 ID입니다. |
| 사용자 액세스 | 로그인한 사용자는 Fabric Real-Time 대시보드를 열 수 있습니다. 포함된 대시보드는 해당 사용자의 위임된 권한을 사용합니다. |
메모
Microsoft Fabric Embed는 공개 미리 보기로 제공됩니다. 지원되는 항목 유형 및 인증 제한 사항은 Microsoft Fabric 포함에 대한 제한을 참조하세요.
MSAL.js 및 Fabric 임베드 SDK 설치
웹앱 프로젝트 폴더에서 이 빠른 시작에서 사용하는 클라이언트 쪽 패키지를 설치합니다.
npm install @azure/msal-browser @microsoft/fabric-embed
미리 보기용 온보딩 지침에서 버전별 Fabric Embed SDK 패키지 명령을 제공하는 경우 @microsoft/fabric-embed 패키지에는 해당 명령을 사용하세요. 설치 후 dependencies에서 package.json에 @azure/msal-browser 및 @microsoft/fabric-embed가 나열되는지 확인합니다.
Microsoft Fabric Embed용 Microsoft Entra 인증 구성
MSAL.js(@azure/msal-browser)는 사용자를 로그인시키고 https://api.fabric.microsoft.com에 대해 Microsoft ID 플랫폼에서 위임된 액세스 토큰을 가져옵니다.
.default 범위는 앱 등록에 대해 이미 동의한 위임된 Fabric 권한(Fabric.Embed 및 Item.Read.All 포함)을 Microsoft Entra ID에 요청합니다.
자세한 내용은 MSAL(Microsoft 인증 라이브러리) 개요를 참조하세요.
임베드 코드가 getAccessToken()를 호출하기 전에 앱의 클라이언트 측 인증 파일 또는 모듈에 이 코드를 추가하세요.
import {
AuthenticationResult,
InteractionRequiredAuthError,
PublicClientApplication,
} from "@azure/msal-browser";
const msal = new PublicClientApplication({
auth: {
clientId: "<client-id>",
authority: "https://login.microsoftonline.com/<tenant-id>",
redirectUri: window.location.origin,
},
});
const defaultScopes = ["https://api.fabric.microsoft.com/.default"];
async function getAccessToken(requestedScopes?: string[]): Promise<string> {
const scopes = requestedScopes ?? defaultScopes;
let accounts = msal.getAllAccounts();
if (accounts.length === 0) {
await msal.loginPopup({ scopes });
accounts = msal.getAllAccounts();
}
const account = accounts[0];
if (!account) {
throw new Error("No Microsoft Entra account is signed in.");
}
let result: AuthenticationResult;
try {
result = await msal.acquireTokenSilent({ scopes, account });
} catch (error) {
if (error instanceof InteractionRequiredAuthError) {
result = await msal.acquireTokenPopup({ scopes, account });
} else {
throw error;
}
}
return result.accessToken;
}
꺾쇠 괄호를 포함한 <client-id> 및 <tenant-id>를 Microsoft Entra 앱 등록 값으로 바꾸세요.
getAccessToken() 함수는 로그인한 Microsoft Entra 사용자에 대해 위임된 Microsoft Fabric 액세스 토큰을 반환하거나, 로그인한 사용자가 없는 경우 오류를 발생시킵니다.
포함된 Real-Time 대시보드에 대한 HTML 컨테이너 추가
Fabric Embed SDK가 Microsoft Fabric Real-Time 대시보드를 렌더링하는 HTML 요소를 추가합니다. 값은 id 포함 코드의 컨테이너 조회와 일치해야 합니다.
role 및 aria-label은 화면 읽기 프로그램 사용자를 위해 임베드된 대시보드 영역을 식별합니다.
<div
id="fabric-embed-container"
role="region"
aria-label="Embedded Fabric Real-Time Dashboard"
></div>
Fabric 임베드 SDK 토큰 새로 고침을 위한 액세스 토큰 공급자 구성
Fabric Embed SDK가 포함된 Real-Time 대시보드에 대해 위임된 Microsoft Fabric 액세스 토큰을 새로 고치는 데 사용하는 액세스 토큰 공급자를 구성합니다. 다음 예제에서는 getAccessToken() 함수를 사용하여 accessTokenProvider를 구현합니다.
const accessTokenProvider = {
callback: async (input?: { scopes?: string[] }) => {
const token = await getAccessToken(input?.scopes);
return { token };
},
};
Fabric 임베드 SDK를 사용하여 실시간 대시보드 임베드하기
Fabric Embed SDK를 사용하여 HTML 컨테이너에서 Microsoft Fabric Real-Time 대시보드를 렌더링합니다. 이 샘플에서 사용하는 공개 미리 보기 SDK 유형은 Real-Time Dashboard 임베딩을 위한 KQLDashboard* 이름을 사용합니다.
embed 구성은 이러한 값을 사용합니다.
| 구성 필드 | Value |
|---|---|
itemId |
사전 요구 사항의 Real-Time 대시보드 항목 ID입니다. |
workspaceId |
사전 요구 사항의 Microsoft Fabric 작업 영역 ID |
accessToken |
getAccessToken()에서 반환한 위임된 Microsoft Fabric 액세스 토큰입니다. |
accessTokenProvider |
포함된 대시보드에 대한 위임된 토큰을 새로 고치는 콜백입니다. |
viewMode |
KQLDashboardViewMode.View- 대시보드를 표시할 수 있도록 렌더링합니다. |
import {
EmbedManager,
KQLDashboardEmbedClient,
KQLDashboardViewMode,
KQLDashboardEmbedConfiguration,
} from "@microsoft/fabric-embed";
const embedManager = new EmbedManager({
embedClientClasses: [KQLDashboardEmbedClient],
});
async function embedDashboard() {
const container = document.getElementById("fabric-embed-container");
if (!container) {
throw new Error("The Fabric embed container was not found.");
}
const token = await getAccessToken();
const embedConfig: KQLDashboardEmbedConfiguration = {
accessToken: { token },
itemId: "<real-time-dashboard-item-id>",
itemType: "KQLDashboard",
workspaceId: "<workspace-id>",
viewMode: KQLDashboardViewMode.View,
eventHooks: { accessTokenProvider },
};
const client: KQLDashboardEmbedClient = embedManager.embed(container, embedConfig);
client.on("rendered", () => {
console.log("Real-Time Dashboard rendered.");
});
client.on("error", (error: unknown) => {
console.error("Microsoft Fabric Embed error:", error);
});
}
embedDashboard();
꺾쇠 괄호를 포함한 <real-time-dashboard-item-id> 및 <workspace-id>을 Fabric 항목 ID 및 작업 영역 ID로 바꾸세요.
코드가 실행되면 SDK는 컨테이너에서 Real-Time 대시보드를 렌더링하고 브라우저 콘솔에 씁니다 Real-Time Dashboard rendered. .
Important
이 문서의 SDK 형식 이름은 공개 미리 보기 용어를 사용합니다. 설치된 미리 보기 패키지에서 다른 형식 이름을 사용하는 경우 해당 패키지 버전의 이름을 사용합니다. 다른 미리 보기 계약 주의 사항은 Microsoft Fabric 포함에 대한 제한을 참조하세요.
Microsoft Fabric Embed Real-Time 대시보드 확인
대시보드가 fabric-embed-container 영역에 표시되고 브라우저 콘솔에 Real-Time Dashboard rendered.가 기록되면 SDK가 대시보드를 성공적으로 임베드한 것입니다.
대시보드가 렌더링되지 않는 경우 SDK error 이벤트 세부 정보를 사용하고 이러한 항목을 확인합니다.
| 확인 | 확인할 내용 |
|---|---|
| 사용자 액세스 | 로그인한 Microsoft Entra 사용자는 Fabric Real-Time 대시보드를 열 수 있습니다. |
| 용량 | 실시간 대시보드를 포함하는 작업 영역은 활성 Fabric 용량에 할당됩니다. |
| URI 리디렉션 | Microsoft Entra 앱 등록에는 웹앱에 대한 리디렉션 URI가 포함됩니다. |
| 위임된 권한 | 앱 등록에는 Fabric.Embed 및 Item.Read.All(또는 KQLDashboard.Read.All)에 대한 위임된 동의가 있으며, 토큰 요청에는 Fabric .default 스코프가 사용됩니다. |
| Identifiers | 작업 영역 ID 및 Real-Time 대시보드 항목 ID는 포함하려는 Fabric 콘텐츠와 일치합니다. |
| HTML 컨테이너 |
fabric-embed-container 요소가 존재하고, 접근 가능한 이름이 있으며, 앱 레이아웃에서 키보드로 계속 접근할 수 있습니다. |
| SDK 오류 처리 | 앱은 Fabric Embed SDK error 이벤트를 처리하고 오류 세부 정보를 기록합니다. |