Introdução rápida à incorporação do Microsoft Fabric

Neste Início rápido, utiliza o Fabric Embed para adicionar um Microsoft Fabric Real-Time Dashboard a uma aplicação Web em JavaScript ou TypeScript executada no browser. Ao usar o Fabric Embed, a sua aplicação pode mostrar o painel de controlo enquanto os utilizadores o acedem, utilizando a sua identidade Microsoft Entra ID e permissões delegadas.

A aplicação utiliza o Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) para solicitar um token de acesso delegado para o recurso da API Microsoft Fabric e o SDK Fabric Embed para renderizar o dashboard. Quando termina, a sua aplicação mostra o Real-Time Dashboard sem enviar os utilizadores para o portal Fabric.

Pré-requisitos para incorporar um Real-Time Dashboard

Antes de começar, complete Configure o seu ambiente para o Microsoft Fabric Embed. Essa configuração cria ou confirma o registo da aplicação Microsoft Entra, permissões delegadas, espaço de trabalho Microsoft Fabric, capacidade ativa do Fabric e valores do painel que este quickstart utiliza.

Também precisa dos seguintes valores e permissões.

Requisito	Description
Projeto de aplicação web	Uma aplicação JavaScript ou TypeScript baseada em browser que utiliza npm. O código de incorporação neste quickstart corre do lado do cliente.
ID do cliente de registo da aplicação Microsoft Entra	O ID do cliente para o registo da aplicação que inicia sessão de utilizadores usando MSAL.js.
ID do locatário Microsoft Entra	O ID do inquilino no qual estão configurados o registo da aplicação e os utilizadores do Fabric.
Permissões delegadas da API	Consentimento delegado para Fabric.Embed e Item.Read.All. O pedido de token MSAL utiliza o âmbito Fabric .default para solicitar estas permissões consentidas.
ID do espaço de trabalho	O ID do espaço de trabalho do Microsoft Fabric que contém o Dashboard em Tempo Real e está atribuído a uma capacidade ativa do Fabric.
ID do item do painel em tempo real	O ID do item do Microsoft Fabric para o Painel em Tempo Real que pretende incorporar.
Acesso do usuário	O utilizador iniciado pode abrir o Real-Time Dashboard em Fabric. O painel embutido utiliza as permissões delegadas por esse utilizador.

Note

O Microsoft Fabric Embed está em pré-visualização pública. Para tipos de itens suportados e limitações de autenticação, consulte Limitações para Microsoft Fabric Embed.

Instala MSAL.js e o SDK Fabric embed

A partir da pasta do projeto da tua aplicação web, instala os pacotes do lado do cliente que este quickstart utiliza.

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

Se as instruções de introdução da versão de pré-visualização incluírem um comando do pacote Fabric Embed SDK específico de uma versão, utilize esse comando para o pacote @microsoft/fabric-embed. Após a instalação, confirme que package.json lista @azure/msal-browser e @microsoft/fabric-embed em dependencies.

Configurar autenticação Microsoft Entra para Microsoft Fabric Embed

MSAL.js (@azure/msal-browser) inicia sessão do utilizador e obtém um token de acesso delegado da plataforma de identidades da Microsoft para https://api.fabric.microsoft.com. O âmbito .default solicita ao Microsoft Entra ID permissões delegadas do Fabric às quais já deu consentimento na inscrição da aplicação, incluindo Fabric.Embed e Item.Read.All.

Para mais informações, consulte a visão geral da Biblioteca de Autenticação da Microsoft (MSAL).

Adicione este código ao ficheiro ou módulo de autenticação do lado do cliente da sua aplicação antes de o código de incorporação chamar 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;
}

Substitua <client-id> e <tenant-id>, incluindo os colchetes angulares, pelos valores do registo da sua aplicação Microsoft Entra. A função getAccessToken() devolve um token de acesso delegado do Microsoft Fabric para o utilizador do Microsoft Entra com sessão iniciada ou gera um erro se nenhum utilizador tiver iniciado sessão.

Adicione um contentor HTML para o Real-Time Dashboard incorporado

Adicione um elemento HTML no qual o SDK Fabric Embed renderiza o Microsoft Fabric Real-Time Dashboard. O valor id deve corresponder à referência ao contentor no código incorporado. role e aria-label identificam a região do painel incorporado para utilizadores de leitores de ecrã.

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

Configurar um fornecedor de token de acesso para a atualização do token do Fabric embed SDK

Configure o fornecedor do token de acesso que o SDK de incorporação do Fabric utiliza para atualizar os tokens de acesso delegados do Microsoft Fabric para o Real-Time Dashboard incorporado. O exemplo seguinte implementa accessTokenProvider usando a getAccessToken() função.

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

Incorpore o dashboard em tempo real com o SDK de incorporação do Fabric

Usa o SDK Fabric Embed para renderizar o Microsoft Fabric Real-Time Dashboard no contentor HTML. Os tipos do SDK em pré-visualização pública neste exemplo usam nomes KQLDashboard* para a incorporação do Dashboard em Tempo Real.

A configuração embed utiliza estes valores.

Campo de configuração	Value
itemId	O ID do item do painel em tempo real dos pré-requisitos.
workspaceId	O ID do espaço de trabalho do Microsoft Fabric indicado nos pré-requisitos.
accessToken	O token de acesso delegado do Microsoft Fabric devolvido por getAccessToken().
accessTokenProvider	O callback que atualiza os tokens delegados para o painel incorporado.
viewMode	KQLDashboardViewMode.View, que renderiza o painel para visualização.

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

Substitua <real-time-dashboard-item-id> e <workspace-id>, incluindo os parênteses angulares, pelos identificadores do seu item do Fabric e do espaço de trabalho.

Quando o código é executado, o SDK renderiza o Real-Time Dashboard no contentor e escreve Real-Time Dashboard rendered. na consola do navegador.

Importante

Os nomes dos tipos do SDK neste artigo usam a terminologia de pré-visualização pública. Se o seu pacote de pré-visualização instalado usar nomes de tipos diferentes, use os nomes dessa versão do pacote. Para outras ressalvas sobre o contrato de pré-visualização, consulte Limitações para o Microsoft Fabric Embed.

Verificar o dashboard em tempo real do Microsoft Fabric Embed

O SDK incorpora o dashboard com sucesso quando aparece na fabric-embed-container região e a consola do navegador regista Real-Time Dashboard rendered..

Se o dashboard não renderizar, usa os detalhes do evento do SDK error e verifica estes itens.

Verificar	O que verificar
Acesso do usuário	O utilizador Microsoft Entra iniciado pode abrir o Real-Time Dashboard em Fabric.
Capacidade	O espaço de trabalho que contém o Real-Time Dashboard está associado a uma capacidade ativa do Fabric.
URI de redirecionamento	O registo da aplicação Microsoft Entra inclui o URI de redirecionamento para a sua aplicação web.
Permissões delegadas	O registo da aplicação tem consentimento delegado para Fabric.Embed e Item.Read.All(ou KQLDashboard.Read.All), e o pedido de token utiliza o âmbito Fabric.default.
Identifiers	O ID do espaço de trabalho e o ID do item do Dashboard em Tempo Real coincidem com o conteúdo do Fabric que pretende incorporar.
Contentor HTML	O fabric-embed-container elemento existe, tem um nome acessível e continua acessível por teclado no layout da tua aplicação.
Gestão de erros do SDK	A sua aplicação gere o evento do SDK error do Fabric Embed e regista os detalhes do erro.

Passos seguintes

• O que é o Microsoft Fabric Embed?
• Configure o seu ambiente para o Microsoft Fabric Embed
• Registar uma candidatura em Microsoft Entra ID
• O que é a Inteligência em Tempo Real no Microsoft Fabric?