Inicio rápido de Microsoft Fabric Embed

En esta guía de inicio rápido, usa Fabric Embed para agregar un panel en tiempo real de Microsoft Fabric a una aplicación web de JavaScript o TypeScript basada en el navegador. Al usar Fabric Embed, su aplicación puede mostrar el panel y los usuarios pueden acceder a él con su identidad de Microsoft Entra ID y permisos delegados.

La aplicación usa el Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) para solicitar un token de acceso delegado para el recurso de API de Microsoft Fabric y el SDK de inserción de Fabric para representar el panel. Cuando termine, la aplicación muestra el panel de Real-Time sin enviar usuarios al portal de Fabric.

Requisitos previos para incrustar un panel en tiempo real

Antes de empezar, complete Configurar el entorno para Microsoft Fabric Embed. Esa configuración crea o confirma el registro de aplicaciones de Microsoft Entra, los permisos delegados, el área de trabajo de Microsoft Fabric, la capacidad activa de Fabric y los valores del panel que usa esta guía de inicio rápido.

También necesita los siguientes valores y permisos.

Instalación de MSAL.js y el SDK de inserción de Fabric

Desde la carpeta del proyecto de la aplicación web, instala los paquetes del cliente que se usan en este inicio rápido.

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

Si las instrucciones preliminares de incorporación proporcionan un comando del paquete del SDK de inserción de Fabric específico de una versión, use ese comando para el paquete @microsoft/fabric-embed. Después de la instalación, confirme que package.json enumera @azure/msal-browser y @microsoft/fabric-embed en dependencies.

Configurar la autenticación de Microsoft Entra para la integración de Microsoft Fabric

MSAL.js (@azure/msal-browser) inicia la sesión del usuario y obtiene un token de acceso delegado de la plataforma de identidad de Microsoft para https://api.fabric.microsoft.com. El ámbito .default solicita a Microsoft Entra ID permisos delegados de Fabric para los que ya otorgó su consentimiento en el registro de la aplicación, incluidos Fabric.Embed y Item.Read.All.

Para obtener más información, consulte introducción a Biblioteca de autenticación de Microsoft (MSAL).

Añada este código al archivo o módulo de autenticación del lado del cliente de su aplicación antes de que el código insertado llame a 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;
}

Reemplace <client-id> y <tenant-id>, incluidos los corchetes angulares, por los valores del registro de aplicación de Microsoft Entra. La getAccessToken() función devuelve un token de acceso Microsoft Fabric delegado para el usuario que ha iniciado sesión Microsoft Entra o produce un error si ningún usuario ha iniciado sesión.

Agregar un contenedor HTML para el panel en tiempo real incrustado

Agregue un elemento HTML donde el SDK de inserción de Microsoft Fabric renderiza el panel en tiempo real de Microsoft Fabric. El valor id debe coincidir con la referencia al contenedor en el código de inserción. Los role y aria-label identifican la región del panel integrado para los usuarios de lectores de pantalla.

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

Configurar un proveedor de token de acceso para la actualización de tokens del SDK de inserción de Fabric

Configure el proveedor de tokens de acceso que usa el SDK de inserción de Fabric para renovar los tokens de acceso delegados de Microsoft Fabric para el panel en tiempo real incrustado. En el ejemplo siguiente se implementa accessTokenProvider mediante la getAccessToken() función .

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

Insertar el panel en tiempo real con el SDK de inserción de Fabric

Use el SDK de inserción de Fabric para mostrar el panel en tiempo real de Microsoft Fabric en el contenedor HTML. Los tipos del SDK en vista previa pública de este ejemplo usan nombres KQLDashboard* para la integración del panel en tiempo real.

La configuración de inserción usa estos valores.

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

Reemplace <real-time-dashboard-item-id> y <workspace-id>, incluidos los corchetes angulares, por los identificadores de elemento y área de trabajo de Fabric.

Cuando se ejecuta el código, el SDK representa el panel de Real-Time en el contenedor y escribe Real-Time Dashboard rendered. en la consola del explorador.

Verificar el panel incrustado en tiempo real de Microsoft Fabric

El SDK inserta correctamente el panel cuando aparece en la fabric-embed-container región y la consola del explorador registra Real-Time Dashboard rendered..

Si el panel no se representa, use los detalles del evento del SDK error y compruebe estos elementos.

Pasos siguientes

• ¿Qué es la inserción de Microsoft Fabric?
• Configurar el entorno para Microsoft Fabric Embed
• Registro de una aplicación en Microsoft Entra ID
• ¿Qué es Real-Time Intelligence en Microsoft Fabric?