Compartir a través de

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

  • Artículo

La interfaz de usuario web de Azure Data Explorer se puede insertar 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 azure Data Explorer web U I.

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, evita el uso compartido de datos entre la versión insertada y la no insertada de https://dataexplorer.azure.com.

Controlar 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 insertado web.

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

Siga estos pasos para controlar la autenticación:

  1. En la aplicación, escuche el mensaje 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 una función para asignar al event.data.scope ámbito de Microsoft Entra. Use la tabla siguiente para decidir cómo asignar event.data.scope a Microsoft Entra ámbitos:

    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 desde el punto de conexión de autenticación de Microsoft Entra para el ámbito. Este código reemplaza al 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 al 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
     }, '*');
   }

    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 usa la autenticación.

Insertar paneles

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

  1. Siga los pasos descritos en Autenticación y autorización del cliente web (JavaScript).

  2. Abra el Azure Portal y asegúrese de que ha 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": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
    • 35e917a9-4d95-4062-9d97-5781291353b9es 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 35e917a9-4d95-4062-9d97-5781291353b9

    Si se produce el Request_MultipleObjectsWithSameKeyValue error, significa que la aplicación ya está en el inquilino 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ística

Importante

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

Es posible que la aplicación de hospedaje quiera controlar ciertos 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.

establecer Descripción Valor predeterminado
f-ShowShareMenu Mostrar el elemento de menú compartir true
f-ShowConnectionButtons Mostrar el botón Agregar conexión para agregar un nuevo clúster true
f-ShowOpenNewWindowButton Mostrar el botón abrir en la interfaz de usuario web que abre una nueva ventana del explorador y apunta a https://dataexplorer.azure.com con el clúster y la base de datos correctos en el ámbito false
f-ShowFileMenu Mostrar el menú archivo (descargar, pestaña, contenido, etc.) true
f-ShowToS Mostrar vínculo a los términos de servicio de 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. false
f-PersistAfterEachRun Normalmente, los exploradores se conservan en el evento de descarga. Sin embargo, el evento unload 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 texto de consulta nuevo que nunca se ha ejecutado. false
f-ShowSmoothIngestion Si es true, muestre la experiencia del Asistente para ingesta al hacer clic con el botón derecho en una base de datos. true
f-RefreshConnection Si es true, siempre actualiza el esquema al cargar la página y nunca depende del almacenamiento local. false
f-ShowPageHeader Si es true, muestra el encabezado de página que incluye el título y la configuración de Azure Data Explorer true
f-HideConnectionPane Si es true, el panel de conexión izquierdo no se muestra false
f-SkipMonacoFocusOnInit Corrige el problema de foco al hospedar en iframe false
f-Homepage Habilitación de la página principal y reenrutar 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. false
f-DisableNewDashboard SI es true, oculta la opción para agregar un nuevo panel. false
f-DisableNewDashboard SI es true, oculta la opción de buscar en la lista de paneles. false
f-DisableDashboardEditMenu SI es true, oculta la opción para editar un panel. false
f-DisableDashboardFileMenu SI es true, oculta el botón de menú archivo en un panel. false
f-DisableDashboardShareMenu SI es true, oculta el botón de menú Compartir en un panel. false
f-DisableDashboardDelete SI es true, oculta el botón eliminar del panel. false
f-DisableTileRefresh SI es true, deshabilita el botón actualizar iconos en un panel. false
f-DisableDashboardAutoRefresh SI es true, deshabilita la actualización automática de iconos en un panel. false
f-DisableExploreQuery SI es true, deshabilita el botón explorar consulta de los iconos. false
f-DisableCrossFiltering SI es true, deshabilita la característica de filtrado cruzado en los paneles. false
f-HideDashboardParametersBar SI es true, oculta la barra de parámetros en un panel. false

Contenido relacionado