Guida introduttiva all'incorporamento di Microsoft Fabric

In questa guida introduttiva, userai Fabric Embed per aggiungere un dashboard in tempo reale di Microsoft Fabric a un'app Web JavaScript o TypeScript eseguita nel browser. Usando Fabric Embed, l'app può visualizzare la dashboard mentre gli utenti vi accedono con la propria identità Microsoft Entra ID e con autorizzazioni delegate.

L'app usa il Authentication Library di Microsoft per JavaScript (MSAL.js) per richiedere un token di accesso delegato per la risorsa API Microsoft Fabric e l'SDK di incorporamento Fabric per eseguire il rendering del dashboard. Al termine, l'app visualizza il dashboard Real-Time senza inviare utenti al portale di Fabric.

Prerequisiti per l'incorporamento di un dashboard Real-Time

Prima di iniziare, completa Configura l'ambiente per Microsoft Fabric Embed. Questa configurazione crea o conferma la registrazione dell’app in Microsoft Entra, le autorizzazioni delegate, l’area di lavoro di Microsoft Fabric, la capacità attiva di Fabric e i valori del cruscotto che questa guida introduttiva utilizza.

Sono necessari anche i valori e le autorizzazioni seguenti.

Installa MSAL.js e SDK di incorporamento di Fabric

Dalla cartella del progetto dell'applicazione Web, installa i pacchetti client usati da questa guida introduttiva rapida.

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

Se le istruzioni di onboarding in anteprima forniscono un comando del pacchetto SDK Fabric Embed specifico per la versione, usa tale comando per il pacchetto @microsoft/fabric-embed. Dopo l'installazione, verificare che package.json elenchi @azure/msal-browser e @microsoft/fabric-embed in dependencies.

Configurare l'autenticazione Microsoft Entra per Microsoft Fabric Embed

MSAL.js (@azure/msal-browser) consente all'utente di accedere e acquisisce un token di accesso delegato dalla piattaforma di identità Microsoft per https://api.fabric.microsoft.com. L'ambito .default richiede a Microsoft Entra ID le autorizzazioni delegate di Fabric per cui è già stato espresso il consenso nell'ambito della registrazione dell'app, incluse Fabric.Embed e Item.Read.All.

Per altre informazioni, vedere panoramica di Libreria di Autenticazione Microsoft (MSAL).

Aggiungi questo codice al file o modulo di autenticazione lato client della tua app prima della chiamata a getAccessToken() nel codice di incorporamento.

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

Sostituire <client-id> e <tenant-id>, incluse le parentesi angolari, con i valori della registrazione dell'app Microsoft Entra. La getAccessToken() funzione restituisce un token di accesso Microsoft Fabric delegato per l'utente connesso Microsoft Entra o genera un errore se nessun utente ha eseguito l'accesso.

Aggiungere un contenitore HTML per il dashboard di Real-Time incorporato

Aggiungere un elemento HTML in cui Fabric Embed SDK esegue il rendering del dashboard Microsoft Fabric Real-Time. Il id valore deve corrispondere alla ricerca del contenitore nel codice di incorporamento. I tag role e aria-label identificano l'area della dashboard incorporata per gli utenti di utilità per la lettura dello schermo.

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

Configurare un provider di token di accesso per l'aggiornamento del token dell'SDK di incorporamento di Fabric

Configurare il provider di token di accesso usato da Fabric Embed SDK per aggiornare i token di accesso Microsoft Fabric delegati per il dashboard Real-Time incorporato. L'esempio seguente implementa accessTokenProvider usando la getAccessToken() funzione .

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

Incorpora il dashboard in tempo reale usando l'SDK per l'incorporamento di Fabric

Usare Fabric Embed SDK per eseguire il rendering del dashboard Microsoft Fabric Real-Time nel contenitore HTML. I tipi dell'SDK in anteprima pubblica in questo esempio usano nomi KQLDashboard* per l'incorporamento di Real-Time Dashboard.

La configurazione di incorporamento usa questi valori.

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

Sostituisci <real-time-dashboard-item-id> e <workspace-id>, incluse le parentesi angolari, con gli ID del tuo elemento Fabric e della tua area di lavoro.

Quando il codice viene eseguito, l'SDK esegue il rendering del dashboard Real-Time nel contenitore e scrive Real-Time Dashboard rendered. nella console del browser.

Verifica il dashboard incorporato di Microsoft Fabric in tempo reale

L'SDK incorpora correttamente il dashboard quando viene visualizzato nell'area fabric-embed-container e la console del browser registra Real-Time Dashboard rendered..

Se il dashboard non viene visualizzato, usa i dettagli dell'evento dell'SDK error e controlla questi elementi.

Passaggi successivi

• Che cos'è Microsoft Fabric Embed?
• Configurare l'ambiente per Microsoft Fabric Embed
• Registrare un'applicazione in Microsoft Entra ID
• Che cos'è Real-Time Intelligence in Microsoft Fabric?