Inserir a interface do usuário da Web do Azure Data Explorer em um iframe

Artigo
03/31/2025

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

A interface do usuário da Web do Azure Data Explorer pode ser inserida em um iframe e hospedada em sites de terceiros. Este artigo descreve como inserir a interface do usuário da Web do Azure Data Explorer em um iframe.

Captura de tela da interface do usuário Web do Azure Data Explorer.

Todas as funcionalidades são testadas quanto à acessibilidade e suportam temas escuros e claros na tela.

Como inserir a interface do usuário da Web em um iframe

Adicione o seguinte código ao seu site:

<iframe
  src="https://dataexplorer.azure.com/?f-IFrameAuth=true&f-UseMeControl=false&workspace=<guid>"
></iframe>

O parâmetro de consulta f-IFrameAuth informa a interface da Web para não redirecionar para obter um token de autenticação, e o parâmetro f-UseMeControl=false informa a interface da Web para não mostrar a janela pop-up com as informações da conta do usuário. Essas ações são necessárias, pois o site de hospedagem é responsável pela autenticação.

O workspace=<guid> parâmetro de consulta cria um espaço de trabalho separado para o iframe incorporado. O espaço de trabalho é uma unidade lógica que contém guias, consultas, configurações e conexões. Ao defini-lo como um valor exclusivo, ele impede o compartilhamento de dados entre a versão incorporada e a não incorporada do https://dataexplorer.azure.com.

Gerenciar autenticação

Ao inserir a interface do usuário da Web, a página de hospedagem é responsável pela autenticação. Os diagramas a seguir descrevem o fluxo de autenticação.

Use as seguintes etapas para lidar com a autenticação:

No aplicativo, veja se você ouve a mensagem getToken.

window.addEventListener('message', (event) => {
   if (event.origin === "https://dataexplorer.azure.com" && event.data.type === "getToken") {
     // CODE-1: Replace this placeholder with code to get the access token from Microsoft Entra ID and
     //         then post a "postToken" message with an access token and an event.data.scope
   }
})

Defina uma função para mapear o event.data.scope ao escopo do Microsoft Entra. Use a tabela a seguir para decidir como mapear event.data.scope para escopos do Microsoft Entra:

Recurso	event.data.scope	Escopo do Microsoft Entra
Agrupamento	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Gráfico	`People.Read`	`People.Read`, `User.ReadBasic.All`, `Group.Read.All`
Painéis	`https://rtd-metadata.azurewebsites.net/user_impersonation`	`https://rtd-metadata.azurewebsites.net/user_impersonation`

Por exemplo, a função a seguir mapeia escopos com base nas informações da tabela.

    function mapScope(scope) {
        switch(scope) {
            case "query": return ["https://your_cluster.your_region.kusto.windows.net/.default"];
            case "People.Read": return ["People.Read", "User.ReadBasic.All", "Group.Read.All"];
            default: return [scope]
        }
    }

Obtenha um token de acesso JWT em Fazer a autenticação de SPA (aplicativo de página única) para o escopo. Este código substitui o marcador CODE-1.

Por exemplo, você pode usar @azure/MSAL-react para obter o token de acesso. O exemplo usa a função mapScope que você definiu anteriormente.
```
import { useMsal } from "@azure/msal-react";
const { instance, accounts } = useMsal();

instance.acquireTokenSilent({
  scopes: mapScope(event.data.scope),
  account: accounts[0],
})
.then((response) =>
    var accessToken = response.accessToken
    // - CODE-2: Replace this placeholder with code to post a "postToken" message with an access token and an event.data.scope
)
```
Importante

Você só pode usar o Nome UPN (Nome Principal do Usuário) para autenticação, não há suporte para entidades de serviço.
Poste uma mensagem postToken com o token de acesso. Este código substitui o placeholder CODE-2:
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, 'https://dataexplorer.azure.com'); 
   }
```
Importante

A janela de hospedagem deve atualizar o token antes da expiração, enviando uma nova mensagem postToken com tokens atualizados. Caso contrário, quando os tokens expirarem, as chamadas de serviço falharão.

Dica

Em nosso projeto de exemplo, você pode exibir um aplicativo que usa autenticação.

Inserir painéis

Para incorporar um painel de controle, uma relação de confiança deve ser estabelecida entre o aplicativo Microsoft Entra do host e o serviço de painel de controle do Azure Data Explorer (Serviço de Metadados RTD).

Siga as etapas em Executar autenticação de aplicativo de página única (SPA).
Abra o Azure portal e verifique se você está conectado ao locatário correto. No canto superior direito, verifique a identidade usada para entrar no portal.
No painel de recursos, selecione Registros do aplicativo ID>do Microsoft Entra.
Localize o aplicativo que usa o Fluxo On-Behalf-Of e abra-o.
Selecione Manifesto.
Selecione requiredResourceAccess.
No manifesto, adicione a seguinte entrada:
```
  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 00001111-aaaa-2222-bbbb-3333cccc4444 é a ID do aplicativo do serviço de painel do Azure Data Explorer.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c é a permissão user_impersonation.
No Manifesto, salve suas alterações.
Selecione Permissões de API e valide se você tem uma nova entrada: RTD Metadata Service.
Em Microsoft Graph, adicione permissões para People.Read, User.ReadBasic.Alle Group.Read.All.
No Azure PowerShell, adicione a seguinte nova entidade de serviço para o aplicativo:
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
Se você encontrar o erro Request_MultipleObjectsWithSameKeyValue, isso significará que o aplicativo já está no locatário, indicando que ele foi adicionado com êxito.
Na página Permissões da API, selecione Conceder consentimento do administrador para consentimento para todos os usuários.

Observação

Para inserir um painel sem a área de consulta, use a seguinte configuração:

 <iframe src="https://dataexplorer.azure.com/dashboards?[feature-flags]" />

onde [feature-flags] está:

"f-IFrameAuth": true,
"f-PersistAfterEachRun": true,
"f-Homepage": false,
"f-ShowPageHeader": false,
"f-ShowNavigation": false,
"f-DisableExploreQuery": false,

Sinalizadores de recursos

Importante

O f-IFrameAuth=true sinalizador é necessário para que o iframe funcione. Os outros sinalizadores são opcionais.

O aplicativo de hospedagem pode querer controlar certos aspectos da experiência do usuário. Por exemplo, oculte o painel de conexão ou desabilite a conexão com outros clusters. Para esse cenário, o Web Explorer dá suporte a sinalizadores de recursos.

Um sinalizador de recurso pode ser usado na URL como um parâmetro de consulta. Para desabilitar a adição de outros clusters, use https://dataexplorer.azure.com/?f-ShowConnectionButtons=false no aplicativo de hospedagem.

configuração	Descrição	Valor Padrão
f-ShowShareMenu	Mostrar o item de menu de compartilhamento	verdadeiro
f-ShowConnectionButtons	Mostrar o botão adicionar conexão para adicionar um novo cluster	verdadeiro
f-ShowOpenNewWindowButton	Mostre o botão da interface do usuário Abrir na Web que abre uma nova janela do navegador e aponta para https://dataexplorer.azure.com com o cluster e o banco de dados corretos no escopo	false
f-ShowFileMenu	Mostrar o menu de arquivo (download, guia, conteúdo e assim por diante)	verdadeiro
f-ShowToS	Mostrar link para os termos de serviço do Azure Data Explorer na caixa de diálogo de configurações	true
f-ShowPersona	Mostre o nome de usuário no menu de configurações, no canto superior direito.	verdadeiro
f-UseMeControl	Mostrar as informações da conta do usuário	verdadeiro
f-IFrameAuth	Se true, o Web Explorer espera que o iframe manipule a autenticação e forneça um token por meio de uma mensagem. Esse parâmetro é necessário para cenários de iframe.	falso
f-PersistAfterEachRun	Normalmente, os navegadores persistem no evento de descarregamento. No entanto, o evento unload nem sempre é disparado quando hospedado em um iframe. Esse sinalizador dispara o evento de estado local persistente após cada execução de consulta. Isso limita qualquer perda de dados que possa ocorrer, para afetar apenas o novo texto de consulta que nunca foi executado.	falso
f-ShowSmoothIngestion	Se true, mostra a experiência do assistente de ingestão ao clicar com o botão direito do mouse em um banco de dados	verdadeiro
f-RefreshConnection	Se true, sempre atualiza o esquema ao carregar a página e nunca depende do armazenamento local	falso
f-ShowPageHeader	Se true, mostra o cabeçalho da página que inclui o título e as configurações do Azure Data Explorer	verdadeiro
f-HideConnectionPane	Se for verdadeiro, o painel de conexão esquerdo não será exibido	falso
f-SkipMonacoFocusOnInit	Corrige o problema de foco ao hospedar no iframe	falso
f-Página inicial	Ative a página inicial e redirecione novos usuários para ela	verdadeiro
f-ShowNavigation	IF true, mostra o painel de navegação à esquerda	verdadeiro
f-DisableDashboardTopBar	Se true, oculta a barra superior no painel	falso
f-DisableNewDashboard	Se verdadeiro, oculta a opção de adicionar um novo painel	falso
f-DisableNewDashboard	Se true, oculta a opção de pesquisa na lista de dashboards	falso
f-DisableDashboardEditMenu	Se verdadeiro, oculta a opção de editar um painel	falso
f-DisableDashboardFileMenu	Se verdadeiro, oculta o botão do menu de arquivos em um painel	falso
f-DisableDashboardShareMenu	IF true, oculta o botão de menu de compartilhamento em um painel	falso
f-DisableDashboardDelete	SE verdadeiro, oculta o botão de exclusão do painel	falso
f-DisableTileRefresh	Se true, desabilita o botão Atualizar blocos em um dashboard	falso
f-DesativarAtualizaçãoAutomáticaDoPainel	IF true, desabilita a atualização automática de tiles em dashboard	false
f-DisableExploreQuery	Se true, desabilita o botão Explorar consulta dos blocos	falso
f-DisableCrossFiltering	IF true, desabilita o recurso de filtragem cruzada em painéis	falso
f-HideDashboardParametersBar	IF true, oculta a barra de parâmetros em um painel	falso

Compartilhar via

Inserir a interface do usuário da Web do Azure Data Explorer em um iframe

Como inserir a interface do usuário da Web em um iframe

Gerenciar autenticação

Inserir painéis

Sinalizadores de recursos

Comentários

Recursos adicionais

Compartilhar via

Inserir a interface do usuário da Web do Azure Data Explorer em um iframe

Como inserir a interface do usuário da Web em um iframe

Gerenciar autenticação

Inserir painéis

Sinalizadores de recursos

Conteúdo relacionado

Comentários

Recursos adicionais