Quickstart til Microsoft Fabric Embed

I denne Quickstart bruger du Fabric Embed til at tilføje et Microsoft Fabric Real-Time Dashboard til en browserbaseret JavaScript- eller TypeScript-webapp. Ved at bruge Fabric Embed kan din app vise dashboardet, mens brugerne tilgår det, ved at bruge deres Microsoft Entra ID-identitet og delegerede tilladelser.

Appen bruger Microsoft Authentication Library for JavaScript (MSAL.js) til at anmode om en delegeret adgangstoken til Microsoft Fabric API-ressourcen og Fabric Embed SDK til at gengive dashboardet. Når du er færdig, viser din app Real-Time Dashboard uden at sende brugere til Fabric-portalen.

Forudsætninger for at indlejre et Real-Time Dashboard

Før du går i gang, skal du færdiggøre Opsætning af dit miljø til Microsoft Fabric Embed. Denne opsætning opretter eller bekræfter Microsoft Entra-appregistreringen, delegerede tilladelser, Microsoft Fabric-arbejdsområdet, aktiv Fabric-kapacitet og dashboardværdier, som denne quickstart bruger.

Du skal også bruge følgende værdier og tilladelser.

Krav	Beskrivelse
Webapp-projekt	En browserbaseret JavaScript- eller TypeScript-app, der bruger npm. Indlejringskoden i denne quickstart kører på klientsiden.
Microsoft Entra app registreringsklient-ID	Klient-ID'et for app-registreringen, der logger brugere ind ved at bruge MSAL.js.
Microsoft Entra tenant ID	Lejer-ID'et, hvor app-registreringen og Fabric-brugerne er konfigureret.
Delegerede API-tilladelser	Delegeret samtykke til Fabric.Embed og Item.Read.All. MSAL-tokenanmodningen bruger Fabric-scope .default til at anmode om disse samtykkede tilladelser.
Arbejdsområde-id	Det Microsoft Fabric arbejdsområde-ID, der indeholder Real-Time Dashboard og er tildelt en aktiv Fabric kapacitet.
Real-Time Dashboard-item-ID	Det Microsoft Fabric item-ID for det Real-Time Dashboard, du vil indlejre.
Brugeradgang	Den indloggede bruger kan åbne Real-Time Dashboard i Fabric. Det indlejrede dashboard bruger brugerens delegerede tilladelser.

Bemærk

Microsoft Fabric Embed er i offentlig forhåndsvisning. For understøttede varetyper og autentificeringsbegrænsninger, se Begrænsninger for Microsoft Fabric Embed.

Installer MSAL.js og Fabric embed SDK

Fra din webapp-projektmappe installerer du de klientside-pakker, som denne quickstart bruger.

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

Hvis dine introduktionsinstruktioner til forhåndsvisning indeholder en versionsspecifik Fabric Embed SDK-pakkekommando, så brug den kommando til @microsoft/fabric-embed pakken. Efter installation, bekræft at package.json der står og @azure/msal-browser@microsoft/fabric-embed i dependencies.

Konfigurér Microsoft Entra-autentificering til Microsoft Fabric Embed

MSAL.js (@azure/msal-browser) logger brugeren ind og får en delegeret adgangstoken fra Microsoft-identitetsplatform for https://api.fabric.microsoft.com. Scopet .default beder Microsoft Entra ID om delegerede Fabric-tilladelser, som du allerede har givet samtykke til til app-registreringen, herunder Fabric.Embed og Item.Read.All.

For mere information, se oversigt over Microsoft Authentication Library (MSAL).

Tilføj denne kode til din apps klientside-autentificeringsfil eller modul før indlejringskodekaldene 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;
}

Erstat <client-id> og <tenant-id>, inklusive vinkelparenteserne, med værdierne fra din Microsoft Entra-appregistrering. Funktionen getAccessToken() returnerer et delegeret Microsoft Fabric-adgangstoken for den indloggede Microsoft Entra-bruger eller giver en fejl, hvis ingen bruger har logget ind.

Tilføj en HTML-container til det indlejrede Real-Time Dashboard

Tilføj et HTML-element, hvor Fabric Embed SDK gengiver det Microsoft Fabric Real-Time Dashboard. Værdien id skal matche containeropslaget i embed-koden. Og rolearia-label identificer det indlejrede dashboard-område for skærmlæserbrugere.

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

Konfigurér en adgangstoken-udbyder til Fabric embed SDK tokenopdatering

Konfigurér den adgangstoken-udbyder, som Fabric Embed SDK bruger til at opdatere delegerede Microsoft Fabric adgangstoks til det indlejrede Real-Time Dashboard. Følgende eksempel implementeres accessTokenProvider ved at bruge funktionen getAccessToken() .

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

Embed Real-Time Dashboard med Fabric embed SDK

Brug Fabric Embed SDK til at gengive Microsoft Fabric Real-Time Dashboard i HTML-containeren. De offentlige preview-SDK-typer i dette eksempel bruger KQLDashboard* navne til Real-Time Dashboard-embedding.

Indlejringskonfigurationen bruger disse værdier.

Konfigurationsfelt	Værdi
itemId	Det Real-Time Dashboard-item-ID fra forudsætningerne.
workspaceId	Microsoft Fabric arbejdsområde-ID fra forudsætningerne.
accessToken	Den delegerede Microsoft Fabric-adgangstoken returneres af getAccessToken().
accessTokenProvider	Callbacken, der opdaterer delegerede tokens til det indlejrede dashboard.
viewMode	KQLDashboardViewMode.View, som gengiver dashboardet til visning.

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

Erstat <real-time-dashboard-item-id> og <workspace-id>, inklusive vinkelbeslagene, med dine Fabric item og workspace ID'er.

Når koden kører, gengiver SDK'en det Real-Time Dashboard i containeren og skriver Real-Time Dashboard rendered. til browserens konsol.

Vigtig

SDK-typenavnene i denne artikel bruger public-preview-terminologi. Hvis din installerede preview-pakke bruger forskellige typenavne, så brug navnene fra den pakkeversion. For andre forbehold om forhåndskontrakter, se Begrænsninger for Microsoft Fabric Embed.

Verificér Microsoft Fabric indlejr Real-Time dashboardet

SDK'en indlejrer dashboardet med succes, når det vises i regionen, fabric-embed-container og browserens konsol logger Real-Time Dashboard rendered..

Hvis dashboardet ikke gengives, brug SDK-hændelsesdetaljerne error og tjek disse elementer.

Kontrollér	Hvad skal man verificere
Brugeradgang	Den indloggede Microsoft Entra bruger kan åbne Real-Time Dashboard i Fabric.
Kapacitet	Arbejdsområdet, der indeholder Real-Time Dashboard, er tildelt en aktiv Fabric kapacitet.
Omdiriger URI	Microsoft Entra-appregistreringen inkluderer omdirigerings-URI'en for din webapp.
Delegerede tilladelser	App-registreringen har delegeret samtykke til Fabric.Embed og (eller KQLDashboard.Read.All), og tokenanmodningen bruger Fabric-scopet .defaultItem.Read.All.
Identifikatorer	Workspace-ID'et og Real-Time dashboard-item ID matcher det Fabric indhold, du ønsker at indlejre.
HTML-beholder	Elementet fabric-embed-container eksisterer, har et tilgængeligt navn og kan stadig nås via tastaturet i dit app-layout.
SDK-fejlhåndtering	Din app håndterer Fabric Embed SDK-hændelsen error og logger fejloplysningerne.

Næste trin

• Hvad er Microsoft Fabric Embed?
• Opsæt dit miljø til Microsoft Fabric Embed
• Registrer et program i Microsoft Entra ID
• Hvad er Real-Time intelligens i Microsoft Fabric?