Schnellstart zum Microsoft Fabric Einbetten

In dieser Schnellstartanleitung verwenden Sie Fabric Einbetten, um einer browserbasierten JavaScript- oder TypeScript-Web-App ein Microsoft Fabric Real-Time Dashboard hinzuzufügen. Mithilfe von Fabric Embed kann Ihre App das Dashboard anzeigen, während Benutzer über ihre Microsoft Entra ID Identität und delegierte Berechtigungen darauf zugreifen.

Die App verwendet die Microsoft Authentication Library für JavaScript (MSAL.js) zum Anfordern eines delegierten Zugriffstokens für die Microsoft Fabric API-Ressource und das Fabric Embed SDK zum Rendern des Dashboards. Wenn Sie fertig sind, zeigt Ihre App das Real-Time Dashboard an, ohne Benutzer an das Fabric Portal zu senden.

Voraussetzungen für das Einbetten eines Real-Time Dashboards

Bevor Sie beginnen, führen Sie "Einrichten Ihrer Umgebung für Microsoft Fabric Embed" aus. Dieses Setup erstellt oder bestätigt die Microsoft Entra-App-Registrierung, delegierte Berechtigungen, den Microsoft Fabric-Arbeitsbereich, die aktive Fabric-Kapazität und die Dashboardwerte, die in dieser Schnellstartanleitung verwendet werden.

Außerdem benötigen Sie die folgenden Werte und Berechtigungen.

Installieren von MSAL.js und dem Fabric Embed SDK

Installieren Sie in Ihrem Web App-Projektordner die clientseitigen Pakete, die diese Schnellstartanleitung verwendet.

npm install @azure/msal-browser @microsoft/fabric-embed

Wenn Ihre Anweisungen für das Vorschau-Onboarding einen versionsspezifischen Fabric Befehl zum Einbetten des SDK-Pakets bereitstellen, verwenden Sie diesen Befehl für das @microsoft/fabric-embed Paket. Vergewissern Sie sich nach der Installation, dass package.json@azure/msal-browser und @microsoft/fabric-embed in dependencies auflistet.

Konfigurieren der Microsoft Entra-Authentifizierung für Microsoft Fabric Embed

MSAL.js (@azure/msal-browser) meldet den Benutzer an und fordert von der Microsoft Identity Platform ein delegiertes Zugriffstoken für https://api.fabric.microsoft.com an. Der .default Scope fordert von Microsoft Entra ID delegierte Fabric-Berechtigungen an, denen Sie für die App-Registrierung bereits zugestimmt haben, einschließlich Fabric.Embed und Item.Read.All.

Weitere Informationen finden Sie unter Microsoft Authentication Library (MSAL) (MSAL)-Übersicht.

Fügen Sie diesen Code vor dem Aufruf von getAccessToken() in die clientseitige Authentifizierungsdatei oder das Modul Ihrer App ein, bevor der Einbettungscode ausgeführt wird.

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

Ersetzen Sie <client-id> und <tenant-id>, einschließlich der spitzen Klammern, durch die Werte aus Ihrer App-Registrierung in Microsoft Entra. Die getAccessToken() Funktion gibt ein delegiertes Microsoft Fabric Zugriffstoken für den angemeldeten Microsoft Entra Benutzer zurück oder löst einen Fehler aus, wenn sich kein Benutzer angemeldet hat.

Hinzufügen eines HTML-Containers für das eingebettete Real-Time-Dashboard

Fügen Sie ein HTML-Element hinzu, bei dem das Fabric Embed SDK das Microsoft Fabric Real-Time Dashboard rendert. Der id Wert muss mit der Containersuche im Einbettungscode übereinstimmen. role und aria-label kennzeichnen den eingebetteten Dashboardbereich für Nutzer von Screenreadern.

<div
  id="fabric-embed-container"
  role="region"
  aria-label="Embedded Fabric Real-Time Dashboard"
></div>

Konfigurieren Sie einen Anbieter für Zugriffstoken für die Tokenaktualisierung im Fabric Embed SDK

Konfigurieren Sie den Zugriffstokenanbieter, den das Fabric Embed SDK verwendet, um delegierte Microsoft Fabric Zugriffstoken für das eingebettete Real-Time-Dashboard zu aktualisieren. Im folgenden Beispiel wird accessTokenProvider mithilfe der Funktion getAccessToken() implementiert.

const accessTokenProvider = {
  callback: async (input?: { scopes?: string[] }) => {
    const token = await getAccessToken(input?.scopes);
    return { token };
  },
};

Einbetten des Real-Time Dashboards mit dem Fabric Embed SDK

Verwenden Sie das Fabric Embed SDK, um das Microsoft Fabric Real-Time Dashboard im HTML-Container zu rendern. Die SDK-Typen der öffentlichen Vorschau in diesem Beispiel verwenden KQLDashboard* Bezeichnungen für die Einbettung von Real-Time Dashboard.

Die Einbettungskonfiguration verwendet diese Werte.

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

Ersetzen Sie <real-time-dashboard-item-id> und <workspace-id>, einschließlich der spitzen Klammern, durch Ihre Fabric-Element- und Arbeitsbereichs-IDs.

Wenn der Code ausgeführt wird, rendert das SDK das Real-Time Dashboard im Container und schreibt Real-Time Dashboard rendered. in die Browserkonsole.

Überprüfen Sie das eingebettete Echtzeitdashboard in Microsoft Fabric

Das SDK bettet das Dashboard erfolgreich ein, wenn es in der fabric-embed-container Region und in den Browserkonsolenprotokollen Real-Time Dashboard rendered.angezeigt wird.

Wenn das Dashboard nicht gerendert wird, verwenden Sie die SDK-Ereignisdetails error , und überprüfen Sie diese Elemente.

Nächste Schritte

• Was ist Microsoft Fabric Embed?
• Einrichten Ihrer Umgebung für Microsoft Fabric Embed
• Registern Sie eine Anwendung in Microsoft Entra ID
• Was ist Real-Time Intelligence in Microsoft Fabric?