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

Artigo
10/30/2024

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 Web do Azure Data Explorer U I.

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 f-IFrameAuth parâmetro de consulta informa à interface do usuário da Web para não redirecionar para obter um token de autenticação e o parâmetro informa f-UseMeControl=false à interface do usuário da Web para não mostrar a janela pop-up de 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.

Manipular 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:

Em seu aplicativo, ouça a mensagem getToken .

window.addEventListener('message', (event) => {
   if (event.data.signature === "queryExplorer" && 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 escopo para o event.data.scope Microsoft Entra. Use a tabela a seguir para decidir como mapear event.data.scope para escopos do Microsoft Entra:

Recurso	evento.data.scope	Escopo do Microsoft Entra
Cluster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Gráfico	`People.Read`	`People.Read`, `User.ReadBasic.All`, `Group.Read.All`
Dashboards	`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 da autenticação Executar Aplicativo de Página Única (SPA) para o escopo. Esse código substitui o espaço reservado 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 espaço reservado CODE-2:
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, '*');
   }
```
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 dashboards

Para inserir um painel, uma relação de confiança deve ser estabelecida entre o aplicativo Microsoft Entra do host e o serviço de painel 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 portal do Azure 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 em nome de 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 Request_MultipleObjectsWithSameKeyValue erro, isso significa que o aplicativo já está no locatário, indicando que 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 recurso

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.

setting	Descrição	Valor Padrão
f-ShowShareMenu	Mostrar o item de menu de compartilhamento	true
f-ShowConnectionButtons	Mostrar o botão adicionar conexão para adicionar um novo cluster	true
f-ShowOpenNewWindowButton	Mostre o botão abrir na interface do usuário da Web que abre uma nova janela do navegador e aponte para https://dataexplorer.azure.com o cluster e o banco de dados corretos no escopo	false
f-MostrarArquivoMenu	Mostrar o menu de arquivo (download, guia, conteúdo e assim por diante)	true
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.	true
f-UseMeControl	Mostrar as informações da conta do usuário	true
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.	false
f-PersistAfterEachRun	Normalmente, os navegadores persistem no evento unload. No entanto, o evento unload nem sempre é disparado ao hospedar 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.	false
f-ShowSmoothIngestion	Se true, mostre a experiência do assistente de ingestão ao clicar com o botão direito do mouse em um banco de dados	true
f-RefreshConnection	Se true, sempre atualiza o esquema ao carregar a página e nunca depende do armazenamento local	false
f-ShowPageHeader	Se true, mostra o cabeçalho da página que inclui o título e as configurações do Azure Data Explorer	true
f-HideConnectionPane	Se true, o painel de conexão esquerdo não será exibido	false
f-SkipMonacoFocusOnInit	Corrige o problema de foco ao hospedar no iframe	false
f-Página inicial	Ative a página inicial e redirecione novos usuários para ela	true
f-ShowNavigation	IF true, mostra o painel de navegação à esquerda	true
f-DisableDashboardTopBar	IF true, oculta a barra superior no painel	false
f-DisableNewDashboard	IF true, oculta a opção de adicionar um novo painel	false
f-DisableNewDashboard	IF true, oculta a opção de pesquisar na lista de painéis	false
f-DisableDashboardEditMenu	IF true, oculta a opção de editar um painel	false
f-DisableDashboardFileMenu	IF true, oculta o botão de menu de arquivo em um painel	false
f-DisableDashboardShareMenu	IF true, oculta o botão de menu de compartilhamento em um painel	false
f-DisableDashboardDelete	IF true, oculta o botão de exclusão do painel	false
f-DisableTileRefresh	SE verdadeiro, desabilita o botão de atualização de blocos em um dashboard	false
f-DisableDashboardAutoRefresh	IF true, desabilita a atualização automática de blocos em um dashboard	false
f-DisableExploreQuery	IF true, desabilita o botão explorar consulta dos blocos	false
f-DisableCrossFiltering	IF true, desabilita o recurso de filtragem cruzada em painéis	false
f-HideDashboardParametersBar	IF true, oculta a barra de parâmetros em um painel	false

Partilhar 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

Manipular autenticação

Inserir dashboards

Sinalizadores de recurso

Comentários

Recursos adicionais

Partilhar 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

Manipular autenticação

Inserir dashboards

Sinalizadores de recurso

Conteúdo relacionado

Comentários

Recursos adicionais