Guia de início rápido da incorporação do Microsoft Fabric

Neste guia de início rápido, você usará o Fabric Embed para adicionar um Painel em Tempo Real do Microsoft Fabric a um aplicativo Web em JavaScript ou TypeScript baseado em navegador. Usando o Fabric Embed, seu aplicativo pode exibir o painel, enquanto os usuários o acessam com sua identidade do Microsoft Entra ID e permissões delegadas.

O aplicativo usa o Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) para solicitar um token de acesso delegado para o recurso de API Microsoft Fabric e o SDK de Inserção Fabric para renderizar o painel. Quando você terminar, seu aplicativo exibirá o Painel de Real-Time sem enviar usuários para o portal Fabric.

Pré-requisitos para incorporar um painel em tempo real

Antes de começar, conclua Configure seu ambiente para o Microsoft Fabric Embed. Essa configuração cria ou confirma o registro do aplicativo do Microsoft Entra, as permissões delegadas, o espaço de trabalho do Microsoft Fabric, a capacidade ativa do Fabric e os valores do painel usados neste início rápido.

Você também precisa dos seguintes valores e permissões.

Instalar MSAL.js e o SDK de inserção Fabric

Na pasta do projeto do aplicativo Web, instale os pacotes do lado do cliente que este início rápido usa.

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

Se as instruções de integração da versão preliminar fornecerem um comando do pacote do SDK Fabric Embed específico da versão, use 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 a autenticação do Microsoft Entra para inserção no Microsoft Fabric

MSAL.js (@azure/msal-browser) conecta o usuário e obtém um token de acesso delegado da plataforma de identidade da Microsoft para https://api.fabric.microsoft.com. O escopo .default solicita ao Microsoft Entra ID as permissões delegadas do Fabric às quais você já concedeu consentimento para o registro do aplicativo, incluindo Fabric.Embed e Item.Read.All.

Para obter mais informações, consulte Visão geral da Biblioteca do Microsoft Authenticator (MSAL).

Adicione este código ao arquivo ou módulo de autenticação no lado do cliente do seu aplicativo antes de o código incorporado 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 registro do aplicativo Microsoft Entra. A getAccessToken() função retorna um token de acesso Microsoft Fabric delegado para o usuário Microsoft Entra conectado ou gera um erro se nenhum usuário tiver se conectado.

Adicionar um contêiner HTML para o Painel em Tempo Real incorporado

Adicione um elemento HTML no qual o SDK de incorporação do Fabric renderiza o Painel em Tempo Real do Microsoft Fabric. O valor de id deve corresponder ao identificador do contêiner no código incorporado. O role e o aria-label identificam a região do painel incorporado para usuários de leitores de tela.

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

Configurar um provedor de token de acesso para a atualização de token do SDK de incorporação do Fabric

Configure o provedor de token de acesso que o SDK de incorporação do Fabric usa para atualizar tokens de acesso delegados do Microsoft Fabric para o Painel em Tempo Real incorporado. O exemplo a seguir 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

Use o SDK de incorporação do Fabric para renderizar o Painel em Tempo Real do Microsoft Fabric no contêiner HTML. Os tipos do SDK de prévia pública neste exemplo usam nomes KQLDashboard* para a incorporação do Painel em Tempo Real.

A configuração de inserção usa esses 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();

Substitua <real-time-dashboard-item-id> e<workspace-id>, incluindo os colchetes angulares, por suas IDs de item e workspace Fabric.

Quando o código é executado, o SDK renderiza o Painel de Real-Time no contêiner e grava Real-Time Dashboard rendered. no console do navegador.

Verificar o dashboard em tempo real incorporado do Microsoft Fabric

O SDK incorpora o painel com sucesso quando ele aparece na região fabric-embed-container e o console do navegador registra Real-Time Dashboard rendered..

Se o painel não for renderizado, use os detalhes do evento do SDK error e verifique esses itens.

Próximas Etapas 

• O que é a Inserção do Microsoft Fabric?
• Configurar seu ambiente para inserir Microsoft Fabric
• Register um aplicativo no Microsoft Entra ID
• O que é Real-Time Intelligence em Microsoft Fabric?