Compartir a través de

Inserción de la interfaz de usuario web de Azure Data Explorer en un iframe

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

La interfaz de usuario web de Azure Data Explorer se puede incrustar en un iframe y hospedarse en sitios web de terceros. En este artículo se describe cómo insertar la interfaz de usuario web de Azure Data Explorer en un iframe.

Captura de pantalla de la interfaz de usuario web de Azure Data Explorer.

Todas las funcionalidades se prueban para la accesibilidad y admiten temas oscuros y claros en pantalla.

Cómo insertar la interfaz de usuario web en un iframe

Agregue el código siguiente al sitio web:

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

El f-IFrameAuth parámetro de consulta indica a la interfaz de usuario web que no redirija para obtener un token de autenticación y el f-UseMeControl=false parámetro indica a la interfaz de usuario web que no muestre la ventana emergente de información de la cuenta de usuario. Estas acciones son necesarias, ya que el sitio web de hospedaje es responsable de la autenticación.

El workspace=<guid> parámetro de consulta crea un área de trabajo independiente para el iframe incrustado. El área de trabajo es una unidad lógica que contiene pestañas, consultas, configuración y conexiones. Al establecerlo en un valor único, impide el uso compartido de datos entre la versión insertada y no insertada de https://dataexplorer.azure.com.

Gestionar la autenticación

Al insertar la interfaz de usuario web, la página de hospedaje es responsable de la autenticación. En los diagramas siguientes se describe el flujo de autenticación.

Diagrama que muestra el flujo de autenticación de un iframe de U I web incrustado.

Diagrama que muestra los ámbitos necesarios para insertar el iframe de U I web.

Siga estos pasos para controlar la autenticación:

  1. En la aplicación, escuche el mensaje 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
   }
})

  2. Defina una función para asignar event.data.scope al ámbito de Microsoft Entra. Use la tabla siguiente para decidir cómo asignar event.data.scope a los ámbitos de Microsoft Entra:

    Recurso event.data.scope Ámbito de Microsoft Entra
    Clúster query https://{your_cluster}.{your_region}.kusto.windows.net/.default
    Grafo People.Read People.Read, , User.ReadBasic.All, Group.Read.All
    Paneles https://rtd-metadata.azurewebsites.net/user_impersonation https://rtd-metadata.azurewebsites.net/user_impersonation

    Por ejemplo, la siguiente función asigna ámbitos en función de la información de la tabla.

        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. Obtenga un token de acceso JWT de la autenticación Realizar aplicación de página única (SPA) para el ámbito. Este código reemplaza el marcador de posición CODE-1.

    Por ejemplo, puede usar @azure/MSAL-react para obtener el token de acceso. En el ejemplo se usa la función mapScope que definió 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

    Solo puede usar el nombre principal de usuario (UPN) para la autenticación, no se admiten las entidades de servicio.

  4. Publique un mensaje postToken con el token de acceso. Este código reemplaza el marcador de posición 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

    La ventana de hospedaje debe actualizar el token antes de la expiración enviando un nuevo mensaje postToken con tokens actualizados. De lo contrario, una vez que expiren los tokens, se producirá un error en las llamadas de servicio.

Sugerencia

En nuestro proyecto de ejemplo, puede ver una aplicación que use la autenticación.

Integrar paneles de control

Para insertar un panel, se debe establecer una relación de confianza entre la aplicación Microsoft Entra del host y el servicio de panel de Azure Data Explorer (RTD Metadata Service).

  1. Siga los pasos descritos en Realizar la autenticación de aplicación de página única (SPA).

  2. Abra el portal de Azure y asegúrese de haber iniciado sesión en el inquilino correcto. En la esquina superior derecha, compruebe la identidad usada para iniciar sesión en el portal.

  3. En el panel de recursos, seleccione Microsoft Entra ID> Registros de aplicaciones.

  4. Busque la aplicación que usa el flujo en nombre de y ábrala.

  5. Seleccione Manifiesto.

  6. Seleccione requiredResourceAccess.

  7. En el manifiesto, agregue la entrada siguiente:

      {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
    • 00001111-aaaa-2222-bbbb-3333cccc4444 es el identificador de aplicación del servicio de panel de Azure Data Explorer.
    • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c es el permiso user_impersonation.

  8. En el manifiesto, guarde los cambios.

  9. Seleccione Permisos de API y valide que tiene una nueva entrada: RTD Metadata Service.

  10. En Microsoft Graph, agregue permisos para People.Read, User.ReadBasic.Ally Group.Read.All.

  11. En Azure PowerShell, agregue la siguiente nueva entidad de servicio para la aplicación:

    New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444

    Si se produce el error Request_MultipleObjectsWithSameKeyValue, significa que la aplicación ya está en el inquilino, lo que indica que se agregó correctamente.

  12. En la página Permisos de API, seleccione Conceder consentimiento del administrador para dar su consentimiento a todos los usuarios.

Nota:

Para insertar un panel sin el área de consulta, use la siguiente configuración:

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

donde [feature-flags] es:

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

Marcas de características

Importante

La f-IFrameAuth=true marca es necesaria para que el iframe funcione. Las otras banderas son opcionales.

Es posible que la aplicación de hospedaje quiera controlar determinados aspectos de la experiencia del usuario. Por ejemplo, oculte el panel de conexión o deshabilite la conexión a otros clústeres. En este escenario, el explorador web admite marcas de características.

Una marca de característica se puede usar en la dirección URL como parámetro de consulta. Para deshabilitar la adición de otros clústeres, use https://dataexplorer.azure.com/?f-ShowConnectionButtons=false en la aplicación de hospedaje.

valor Descripción Valor predeterminado
f-ShowShareMenu Mostrar el elemento del menú de compartir cierto
f-ShowConnectionButtons Mostrar el botón Agregar conexión para agregar un nuevo clúster true
f-ShowOpenNewWindowButton Mostrar el botón de la interfaz de usuario abrir en la web que abre una nueva ventana del explorador y apuntar a https://dataexplorer.azure.com con el clúster y la base de datos correctos en el ámbito falso
f-ShowFileMenu Mostrar el menú de archivo (descargar, pestaña, contenido, etc.) true
f-ShowToS Mostrar vínculo a los términos de servicio para Azure Data Explorer desde el cuadro de diálogo de configuración true
f-ShowPersona Muestra el nombre de usuario en el menú de configuración, en la esquina superior derecha. true
f-UseMeControl Mostrar la información de la cuenta del usuario true
f-IFrameAuth Si es true, el explorador web espera que el iframe controle la autenticación y proporcione un token a través de un mensaje. Este parámetro es necesario para escenarios de iframe. falso
f-PersistAfterEachRun Normalmente, los exploradores persisten en el evento de descarga. Sin embargo, el evento de descarga no siempre se desencadena cuando se hospeda en un iframe. Esta marca desencadena el evento de estado local persistente después de ejecutar cada consulta. Esto limita cualquier pérdida de datos que pueda producirse, para que solo afecte al nuevo texto de consulta que nunca se ha ejecutado. falso
f-ShowSmoothIngestion Si es verdadero, muestre la experiencia del asistente de ingesta de datos al hacer clic con el botón derecho en una base de datos. Verdadero
f-RefreshConnection Si es true, siempre actualiza el esquema al cargar la página y nunca depende del almacenamiento local. falso
f-MostrarEncabezadoDePágina Si es true, muestra el encabezado de página que incluye el título y la configuración de Azure Data Explorer. true
f-OcultarPanelDeConexión Si es true, el panel de conexión izquierdo no se muestra falso
f-SkipMonacoFocusOnInit Corrige el problema de foco al hospedar en iframe falso
f-Página de inicio Habilitación de la página principal y reenrutación de nuevos usuarios a ella true
f-ShowNavigation SI es true, muestra el panel de navegación de la izquierda. true
f-DisableDashboardTopBar SI es true, oculta la barra superior en el panel. falso
f-DisableNewDashboard SI es true, oculta la opción para agregar un nuevo panel. falso
f-DisableNewDashboard Si es true, oculta la opción de buscar en la lista de paneles falso
f-DisableDashboardEditMenu SI es true, oculta la opción para editar un panel. falso
f-DisableDashboardFileMenu Si es verdadero, oculta el botón de menú de archivo en un panel de control. falso
f-DisableDashboardShareMenu Si es true, oculta el botón de menú de compartir en un panel falso
f-DisableDashboardDelete Si es true, oculta el botón de eliminación del panel false
f-DisableTileRefresh Si es true, deshabilita el botón de actualizar iconos en un panel false
f-DesactivarActualizaciónAutomáticaDelTablero SI es true, deshabilita la actualización automática de iconos en un panel. falso
f-DisableExploreQuery Si es true, deshabilita el botón de explorar consulta de los iconos false
f-DisableCrossFiltering si es true, desactiva la característica de filtrado cruzado en los paneles de control. falso
f-OcultarBarraDeParámetrosDelPanel SI es true, oculta la barra de parámetros en un panel. falso

Contenido relacionado