Microsoft Fabric 嵌入快速入門

在這個快速入門中，您將使用 Fabric Embed，在瀏覽器型 JavaScript 或 TypeScript 網頁應用程式中新增 Microsoft Fabric Real-Time Dashboard。透過 Fabric Embed，您的應用程式可顯示儀表板，而使用者則可使用其 Microsoft Entra ID 身分和委派權限來存取該儀表板。

應用程式使用適用於 JavaScript 的 Microsoft Authentication Library（MSAL.js）來請求用於 Microsoft Fabric API 資源的委派存取權杖，並使用 Fabric Embed SDK 來呈現儀表板。完成後，應用程式會顯示 Real-Time 儀表板，且不會將使用者導向Fabric入口。

嵌入 Real-Time 儀表板的前提條件

在開始之前，先完成 Microsoft Fabric Embedded 的環境設定。該設定程序會建立或確認這個快速入門所使用的 Microsoft Entra 應用程式註冊、委派權限、Microsoft Fabric 工作區、作用中的 Fabric 容量，以及儀表板值設定。

你還需要以下的值和權限。

Requirement	Description
網頁應用程式專案	一款基於瀏覽器的 JavaScript 或 TypeScript 應用程式，使用 npm。本快速入門中的嵌入程式碼是在用戶端執行。
Microsoft Entra 應用程式註冊客戶端ID	應用程式註冊時的客戶端 ID，透過 MSAL.js登入使用者。
Microsoft Entra 租戶標識符	租戶 ID 是用來設定應用程式註冊和 Fabric 使用者的。
委派 API 權限	適用於 `Fabric.Embed` 和 `Item.Read.All` 的委派同意。 MSAL 令牌請求使用 Fabric `.default` 範圍來請求這些經同意的權限。
工作區識別碼	包含即時儀表板，且已指派給使用中的 Fabric 容量的 Microsoft Fabric 工作區 ID。
即時儀表板項目識別碼	你想要嵌入之即時儀表板的 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套件。安裝後，請確認 package.json 在 dependencies 中列出 @azure/msal-browser 和 @microsoft/fabric-embed。

為 Microsoft Fabric Embed 設定 Microsoft Entra 認證

MSAL.js（@azure/msal-browser）會讓使用者登入，並為 https://api.fabric.microsoft.com 從 Microsoft 身分識別平台取得委派存取權杖。 .default 範圍會向 Microsoft Entra ID 要求你已為應用程式註冊授與同意的委派 Fabric 權限，包括 Fabric.Embed 和 Item.Read.All。

欲了解更多資訊，請參閱 Microsoft 驗證資源庫（MSAL）概述。

在嵌入碼呼叫 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 存取權杖，若無使用者登入則會拋出錯誤。

新增一個 HTML 容器作為內嵌的 Real-Time 儀表板

新增一個 HTML 元素，讓 Fabric Embed SDK 渲染 Microsoft Fabric Real-Time 儀表板。值 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 類型使用用於即時儀表板內嵌的 KQLDashboard* 名稱。

嵌入配置使用這些值。

配置欄位	Value
`itemId`	Real-Time 儀表板的項目 ID，來自前置條件。
`workspaceId`	來自前置條件的 Microsoft Fabric 工作空間 ID。
`accessToken`	委派的 Microsoft Fabric 存取權杖由 `getAccessToken()`返回。
`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。

當程式碼執行時，SDK 會在容器中渲染 Real-Time 儀表板，然後寫 Real-Time Dashboard rendered. 入瀏覽器主控台。

Important

本文中的 SDK 類型名稱使用公開預覽術語。如果你安裝的預覽套件使用不同類型名稱，請使用該套件版本的名稱。關於其他預覽合約的注意事項，請參見 Microsoft Fabric Embedded 的限制。

驗證 Microsoft Fabric 內嵌的即時儀表板

當儀表板出現在 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 和即時儀表板項目 ID 與您想要內嵌的 Fabric 內容相符。
HTML 容器	這個 `fabric-embed-container` 元素存在，名稱可存取，且在你的應用程式版面中仍可透過鍵盤存取。
SDK 錯誤處理	你的應用程式會處理 Fabric Embed SDK `error` 事件並記錄錯誤細節。

下一步

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-06