Incorporar a IU da Web do Azure Data Explorer num iframe

A IU do Azure Data Explorer Web pode ser incorporada num iframe e alojada em sites de terceiros. Este artigo descreve como incorporar a IU da Web do Azure Data Explorer num iframe.

Captura de ecrã da IU da Web do Azure Data Explorer.

Todas as funcionalidades são testadas para acessibilidade e suporta temas escuros e claros no ecrã.

Como incorporar a IU da Web num 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 indica à IU da Web para não redirecionar para obter um token de autenticação e o f-UseMeControl=false parâmetro indica à IU da Web para não mostrar a janela de pop-up das informações da conta de utilizador. Estas ações são necessárias, uma vez que o site de alojamento é responsável pela autenticação.

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

Processar a autenticação

Ao incorporar a IU da Web, a página de alojamento é responsável pela autenticação. Os diagramas seguintes descrevem o fluxo de autenticação.

Diagrama que mostra o fluxo de autenticação de um iframe I da Web incorporado.

Diagrama que mostra os âmbitos necessários para incorporar o iframe web U I.

Utilize os seguintes passos para processar a autenticação:

  1. Na sua aplicação, 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
       }
    })    
    
  2. Defina uma função para mapear o event.data.scope âmbito para Microsoft Entra. Utilize a tabela seguinte para decidir como mapear event.data.scope para Microsoft Entra âmbitos:

    Recurso event.data.scope Microsoft Entra âmbito
    Cluster query https://{your_cluster}.{your_region}.kusto.windows.net/.default
    Graph 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 seguinte mapeia âmbitos com base nas informações na 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]
            }
        }
    
  3. Obtenha um token de acesso JWT a partir do ponto final de autenticação Microsoft Entra para o âmbito. Este código substitui o marcador de posição CODE-1.

    Por exemplo, pode utilizar @azure/MSAL-react para obter o token de acesso. O exemplo utiliza a função mapScope que 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

    Só pode utilizar o Nome Principal de Utilizador (UPN) para autenticação. Os principais de serviço não são suportados.

  4. Publique uma mensagem postToken com o token de acesso. Este código substitui o marcador de posição 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 alojamento tem de atualizar o token antes da expiração ao enviar uma nova mensagem postToken com tokens atualizados. Caso contrário, quando os tokens expirarem, as chamadas de serviço falharão.

Dica

No nosso projeto de exemplo, pode ver uma aplicação que utiliza autenticação.

Incorporar dashboards

Para incorporar um dashboard, tem de ser estabelecida uma relação de confiança entre a aplicação Microsoft Entra do anfitrião e o serviço de dashboard do Azure Data Explorer (Serviço de Metadados RTD).

  1. Siga os passos na autenticação e autorização do Cliente Web (JavaScript).

  2. Abra o portal do Azure e certifique-se de que tem sessão iniciada no inquilino correto. No canto superior direito, verifique a identidade utilizada para iniciar sessão no portal.

  3. No painel recursos, selecione Microsoft Entra ID>Registos de aplicações.

  4. Localize a aplicação que utiliza o fluxo em nome do e abra-a .

  5. Selecione Manifesto.

  6. Selecione requiredResourceAccess.

  7. No manifesto, adicione a seguinte entrada:

      {
        "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
        "resourceAccess": [
            {
                "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
                "type": "Scope"
            }
        ]
      }
    
    • 35e917a9-4d95-4062-9d97-5781291353b9é o ID da aplicação do serviço de dashboard do Azure Data Explorer.
    • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c é a permissão user_impersonation.
  8. No Manifesto, guarde as alterações.

  9. Selecione Permissões de API e valide se tem uma nova entrada: Serviço de Metadados RTD.

  10. Em Microsoft Graph, adicione permissões para People.Read, User.ReadBasic.Alle Group.Read.All.

  11. Em Azure PowerShell, adicione o seguinte novo principal de serviço para a aplicação:

    New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
    

    Se encontrar o Request_MultipleObjectsWithSameKeyValue erro, significa que a aplicação já está no inquilino a indicar que foi adicionada com êxito.

  12. Na página Permissões da API , selecione Conceder consentimento ao administrador para dar consentimento a todos os utilizadores.

Nota

Para incorporar um dashboard sem a área de consulta, utilize 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 funcionalidades

Importante

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

A aplicação de alojamento poderá querer controlar determinados aspetos da experiência do utilizador. Por exemplo, oculte o painel de ligação ou desative a ligação a outros clusters. Para este cenário, o web explorer suporta sinalizadores de funcionalidades.

Um sinalizador de funcionalidade pode ser utilizado no URL como um parâmetro de consulta. Para desativar a adição de outros clusters, utilize https://dataexplorer.azure.com/?f-ShowConnectionButtons=false na aplicação de alojamento.

definição Description Valor Predefinido
f-ShowShareMenu Mostrar o item de menu partilhar true
f-ShowConnectionButtons Mostrar o botão adicionar ligação para adicionar um novo cluster true
f-ShowOpenNewWindowButton Mostrar o botão abrir na IU da Web que abre uma nova janela do browser e aponta para com o cluster e a https://dataexplorer.azure.com base de dados certos no âmbito false
f-ShowFileMenu Mostrar o menu de ficheiros (transferir, separador, conteúdo, etc.) true
f-ShowToS Mostrar ligação para os termos de serviço do Azure Data Explorer na caixa de diálogo de definições true
f-ShowPersona Mostrar o nome de utilizador no menu de definições, no canto superior direito. true
f-UseMeControl Mostrar as informações da conta do utilizador true
f-IFrameAuth Se for verdade, o explorador Web espera que o iframe processe a autenticação e forneça um token através de uma mensagem. Este parâmetro é necessário para cenários iframe. false
f-PersistAfterEachRun Normalmente, os browsers persistem no evento de descarregamento. No entanto, o evento de descarregamento nem sempre é acionado ao alojar num iframe. Este sinalizador aciona o evento de estado local persistente após cada execução de consulta. Isto limita qualquer perda de dados que possa ocorrer, para afetar apenas o novo texto de consulta que nunca foi executado. false
f-ShowSmoothIngestion Se for verdadeiro, mostre a experiência do assistente de ingestão ao clicar com o botão direito do rato numa base de dados true
f-RefreshConnection Se for verdadeiro, atualiza sempre o esquema ao carregar a página e nunca depende do armazenamento local false
f-ShowPageHeader Se for verdadeiro, mostra o cabeçalho da página que inclui o título e as definições do Azure Data Explorer true
f-HideConnectionPane Se for verdadeiro, o painel de ligação à esquerda não é apresentado false
f-SkipMonacoFocusOnInit Corrige o problema de foco ao alojar no iframe false
f Home page Ativar a home page e reencaminhar novos utilizadores para a mesma true
f-ShowNavigation SE for verdadeiro, mostra o painel de navegação à esquerda true
f-DisableDashboardTopBar SE for verdadeiro, oculta a barra superior no dashboard false
f-DisableNewDashboard SE for verdadeiro, oculta a opção para adicionar um novo dashboard false
f-DisableNewDashboard SE for verdadeiro, oculta a opção para procurar na lista de dashboards false
f-DisableDashboardEditMenu SE for verdadeiro, oculta a opção para editar um dashboard false
f-DisableDashboardFileMenu SE for verdadeiro, oculta o botão do menu de ficheiros num dashboard false
f-DisableDashboardShareMenu SE for verdadeiro, oculta o botão de menu partilhar num dashboard false
f-DisableDashboardDelete SE for verdadeiro, oculta o botão de eliminação do dashboard false
f-DisableTileRefresh SE for verdadeiro, desativa o botão atualizar mosaicos num dashboard false
f-DisableDashboardAutoRefresh SE for verdadeiro, desativa a atualização automática de mosaicos num dashboard false
f-DisableExploreQuery SE for verdadeiro, desativa o botão explorar consulta dos mosaicos false
f-DisableCrossFiltering SE for verdadeiro, desativa a funcionalidade de filtragem cruzada nos dashboards false
f-HideDashboardParametersBar SE for verdadeiro, oculta a barra de parâmetros num dashboard false