Snelstart voor het insluiten van Microsoft Fabric

In deze quickstart gebruikt u Fabric Embed om een Microsoft Fabric Real-Time Dashboard toe te voegen aan een browsergebaseerde JavaScript- of TypeScript-web-app. Met behulp van Fabric Insluiten kan uw app het dashboard weergeven terwijl gebruikers het openen met behulp van hun Microsoft Entra ID identiteit en gedelegeerde machtigingen.

De app gebruikt de Microsoft Authentication Library voor JavaScript (MSAL.js) om een gedelegeerd toegangstoken aan te vragen voor de Microsoft Fabric API-resource en de Fabric Embed SDK om het dashboard weer te geven. Wanneer u klaar bent, wordt in uw app het Real-Time Dashboard weergegeven zonder dat gebruikers naar de Fabric-portal worden verzonden.

Vereisten voor het insluiten van een Real-Time Dashboard

Voordat u begint, voltooit u De omgeving instellen voor Microsoft Fabric Insluiten. Met deze configuratie worden de Microsoft Entra-app-registratie, gedelegeerde machtigingen, de Microsoft Fabric-werkruimte, de actieve Fabric-capaciteit en de dashboardwaarden gemaakt of bevestigd die in deze quickstart worden gebruikt.

U hebt ook de volgende waarden en machtigingen nodig.

Requirement Description
Web-app-project Een browsergebaseerde JavaScript- of TypeScript-app die npm gebruikt. De insluitcode in deze quickstart wordt aan de clientzijde uitgevoerd.
client-id voor app-registratie Microsoft Entra De client-id voor de app-registratie waarmee gebruikers worden aangemeld met behulp van MSAL.js.
Microsoft Entra tenant-ID De tenant-id waar de app-registratie en Fabric gebruikers zijn geconfigureerd.
Gedelegeerde API-machtigingen Gedelegeerde toestemming voor Fabric.Embed en Item.Read.All. De MSAL-tokenaanvraag maakt gebruik van het Fabric .default bereik om deze toestemmingsmachtigingen aan te vragen.
Werkruimte-id De Microsoft Fabric-werkruimte-id die het Realtime-dashboard bevat en is toegewezen aan een actieve Fabric-capaciteit.
item-id van Real-Time Dashboard De Microsoft Fabric item-id voor het Real-Time Dashboard dat u wilt insluiten.
Gebruikerstoegang De aangemelde gebruiker kan het Real-Time Dashboard openen in Fabric. Het ingesloten dashboard maakt gebruik van de gedelegeerde machtigingen van die gebruiker.

Note

Microsoft Fabric Embed is beschikbaar als openbare preview. Zie Beperkingen voor Microsoft Fabric Embed voor ondersteunde itemtypen en verificatiebeperkingen.

Installeer MSAL.js en de Fabric-SDK voor insluiten

Installeer vanuit de projectmap van uw web-app de pakketten aan de clientzijde die in deze quickstart worden gebruikt.

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

Als uw preview-onboardinginstructies een versiespecifieke pakketopdracht voor de Fabric Embed SDK bevatten, gebruikt u die opdracht voor het @microsoft/fabric-embed-pakket. Controleer na de installatie of package.json@azure/msal-browser en @microsoft/fabric-embed in dependencies vermeldt.

Authenticatie van Microsoft Entra voor Microsoft Fabric Embed configureren

MSAL.js (@azure/msal-browser) meldt zich aan bij de gebruiker en verkrijgt een gedelegeerd toegangstoken van de Microsoft identity platform voor https://api.fabric.microsoft.com. Het .default machtigingsbereik vraagt Microsoft Entra ID om gedelegeerde Fabric-machtigingen waar u al toestemming voor hebt verleend voor de app-registratie, waaronder Fabric.Embed en Item.Read.All.

Zie het overzicht van Microsoft Authentication Library (MSAL) voor meer informatie.

Voeg deze code toe aan het client-side-authenticatiebestand of de client-side-authenticatiemodule van je app voordat de insluitcode getAccessToken() aanroept.

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

Vervang <client-id> en <tenant-id>, inclusief de punthaken, door de waarden uit uw Microsoft Entra-app-registratie. De getAccessToken() functie retourneert een gedelegeerd Microsoft Fabric toegangstoken voor de aangemelde Microsoft Entra gebruiker of genereert een fout als er geen gebruiker is aangemeld.

Een HTML-container toevoegen voor het ingesloten Real-Time Dashboard

Voeg een HTML-element toe waarbij de Fabric Embed SDK het Microsoft Fabric Real-Time Dashboard weergeeft. De id waarde moet overeenkomen met de containerzoekactie in de invoegcode. De role en aria-label duiden het ingesloten dashboardgebied voor schermlezergebruikers aan.

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

Een toegangstokenprovider configureren voor tokenvernieuwing in de Fabric embed SDK

Configureer de toegangstokenprovider die de Fabric Embed SDK gebruikt voor het vernieuwen van gedelegeerde Microsoft Fabric toegangstokens voor het ingesloten Real-Time Dashboard. In het volgende voorbeeld wordt accessTokenProvider geïmplementeerd met behulp van de getAccessToken() functie.

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

Het Real-Time Dashboard insluiten met de Fabric-insluitings-SDK

Gebruik de Fabric Embed SDK om het Microsoft Fabric Real-Time Dashboard in de HTML-container weer te geven. De SDK-typen in openbare preview in dit voorbeeld gebruiken KQLDashboard* benamingen voor het insluiten van Real-Time Dashboards.

De insluitingsconfiguratie maakt gebruik van deze waarden.

Configuratieveld Value
itemId De item-ID van het Real-Time-dashboard uit de vereisten.
workspaceId De Microsoft Fabric-werkruimte-id uit de vereisten.
accessToken Het gedelegeerde Microsoft Fabric toegangstoken geretourneerd door getAccessToken().
accessTokenProvider De callback waarmee gedelegeerde tokens voor het ingesloten dashboard worden vernieuwd.
viewMode KQLDashboardViewMode.View, waarmee het dashboard wordt weergegeven. 
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();

Vervang <real-time-dashboard-item-id> en <workspace-id>, inclusief de punthaken, door uw Fabric-item- en werkruimte-id’s.

Wanneer de code wordt uitgevoerd, geeft de SDK het Real-Time Dashboard weer in de container en schrijft Real-Time Dashboard rendered. deze naar de browserconsole.

Important

De typenamen van de SDK in dit artikel gebruiken terminologie voor openbare preview. Als uw geïnstalleerde preview-pakket verschillende typenamen gebruikt, gebruikt u de namen van die pakketversie. Zie Beperkingen voor Microsoft Fabric Embed voor andere voorbehouden met betrekking tot preview-contracten.

De Microsoft Fabric Embed Real-Time-dashboard verifiëren

De SDK sluit het dashboard succesvol in wanneer het wordt weergegeven in de regio fabric-embed-container en de browserconsole Real-Time Dashboard rendered. logt.

Als het dashboard niet wordt weergegeven, gebruikt u de details van de SDK-gebeurtenis error en controleert u deze items.

Controle Wat u moet controleren
Gebruikerstoegang De aangemelde Microsoft Entra gebruiker kan het Real-Time Dashboard openen in Fabric.
Capaciteit De werkruimte met het Real-Time Dashboard wordt toegewezen aan een actieve Fabric capaciteit.
Omleidings-URI De Microsoft Entra app-registratie bevat de omleidings-URI voor uw web-app.
Gedelegeerde machtigingen De app-registratie heeft gedelegeerde toestemming voor Fabric.Embed en Item.Read.All(of KQLDashboard.Read.All), en de tokenaanvraag gebruikt de Fabric-.defaultscope.
Identifiers De werkruimte-id en Real-Time dashboarditem-id komen overeen met de Fabric inhoud die u wilt insluiten.
HTML-container Het fabric-embed-container element bestaat, heeft een toegankelijke naam en blijft bereikbaar via het toetsenbord in de app-indeling.
Afhandeling van SDK-fouten Uw app verwerkt de Fabric Embed SDK-gebeurtenis error en registreert de foutdetails.

Volgende stappen 

  • Laatst bijgewerkt om