Partager via

Incorporer l’interface utilisateur web Azure Data Explorer dans un iframe

  • Article

L’interface utilisateur web Azure Data Explorer peut être incorporée dans un iframe et hébergée sur des sites web tiers. Cet article explique comment incorporer l’interface utilisateur web Azure Data Explorer dans un iframe.

Capture d’écran de l’interface utilisateur web Azure Data Explorer.

Toutes les fonctionnalités sont testées pour l’accessibilité et prennent en charge les thèmes à l’écran sombres et clairs.

Comment incorporer l’interface utilisateur web dans un iframe

Ajoutez le code suivant à votre site web :

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

Le f-IFrameAuth paramètre de requête indique à l’interface utilisateur web de ne pas rediriger pour obtenir un jeton d’authentification et le f-UseMeControl=false paramètre indique à l’interface utilisateur web de ne pas afficher la fenêtre contextuelle des informations de compte d’utilisateur. Ces actions sont nécessaires, car le site web d’hébergement est responsable de l’authentification.

Le workspace=<guid> paramètre de requête crée un espace de travail distinct pour l’iframe incorporé. L’espace de travail est une unité logique qui contient des onglets, des requêtes, des paramètres et des connexions. En lui affectant une valeur unique, il empêche le partage de données entre la version incorporée et la version non incorporée de https://dataexplorer.azure.com.

Gérer l’authentification

Lors de l’incorporation de l’interface utilisateur web, la page d’hébergement est responsable de l’authentification. Les diagrammes suivants décrivent le flux d’authentification.

Diagramme montrant le flux d’authentification pour un iframe U I web incorporé.

Diagramme montrant les étendues requises pour l’incorporation de l’iframe U I web.

Pour gérer l’authentification, procédez comme suit :

  1. Dans votre application, écoutez le message 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. Définissez une fonction pour mapper à event.data.scope Microsoft Entra étendue. Utilisez le tableau suivant pour déterminer comment mapper event.data.scope à Microsoft Entra étendues :

    Ressource event.data.scope étendue Microsoft Entra
    Cluster query https://{your_cluster}.{your_region}.kusto.windows.net/.default
    Graph People.Read People.Read, User.ReadBasic.All, Group.Read.All
    Tableaux de bord https://rtd-metadata.azurewebsites.net/user_impersonation https://rtd-metadata.azurewebsites.net/user_impersonation

    Par exemple, la fonction suivante mappe les étendues en fonction des informations contenues dans la table.

        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. Obtenez un jeton d’accès JWT à partir du point de terminaison d’authentification Microsoft Entra pour l’étendue. Ce code remplace l’espace réservé CODE-1.

    Par exemple, vous pouvez utiliser @azure/MSAL-react pour obtenir le jeton d’accès. L’exemple utilise la fonction mapScope que vous avez définie précédemment.

    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
)

    Important

    Vous ne pouvez utiliser que le nom d’utilisateur principal (UPN) pour l’authentification. Les principaux de service ne sont pas pris en charge.

  4. Publiez un message postToken avec le jeton d’accès. Ce code remplace l’espace réservé CODE-2 :

         iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, '*');
   }

    Important

    La fenêtre d’hébergement doit actualiser le jeton avant l’expiration en envoyant un nouveau message postToken avec des jetons mis à jour. Sinon, une fois les jetons expirés, les appels de service échouent.

Conseil

Dans notre exemple de projet, vous pouvez afficher une application qui utilise l’authentification.

Tableaux de bord incorporés

Pour incorporer un tableau de bord, une relation d’approbation doit être établie entre l’application Microsoft Entra de l’hôte et le service de tableau de bord Azure Data Explorer (RTD Metadata Service).

  1. Suivez les étapes décrites dans Authentification et autorisation du client web (JavaScript).

  2. Ouvrez le Portail Azure et assurez-vous que vous êtes connecté au locataire approprié. En haut à droite, vérifiez l’identité utilisée pour vous connecter au portail.

  3. Dans le volet ressources, sélectionnez MICROSOFT ENTRA ID>inscriptions d'applications.

  4. Recherchez l’application qui utilise le flux on-behalf-of et ouvrez-la .

  5. Sélectionnez Manifeste.

  6. Sélectionnez requiredResourceAccess.

  7. Dans le manifeste, ajoutez l’entrée suivante :

      {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
    • 35e917a9-4d95-4062-9d97-5781291353b9est l’ID d’application du service de tableau de bord Azure Data Explorer.
    • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c est l’autorisation user_impersonation.

  8. Dans le manifeste, enregistrez vos modifications.

  9. Sélectionnez Autorisations d’API et vérifiez que vous disposez d’une nouvelle entrée : RTD Metadata Service.

  10. Sous Microsoft Graph, ajoutez des autorisations pour People.Read, User.ReadBasic.Allet Group.Read.All.

  11. Dans Azure PowerShell, ajoutez le nouveau principal de service suivant pour l’application :

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

    Si vous rencontrez l’erreur Request_MultipleObjectsWithSameKeyValue , cela signifie que l’application se trouve déjà dans le locataire, ce qui indique qu’elle a été ajoutée avec succès.

  12. Dans la page Autorisations de l’API , sélectionnez Accorder le consentement de l’administrateur pour donner son consentement à tous les utilisateurs.

Notes

Pour incorporer un tableau de bord sans la zone de requête, utilisez la configuration suivante :

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

où [feature-flags] est :

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

Indicateurs de fonctionnalités

Important

L’indicateur f-IFrameAuth=true est requis pour que l’iframe fonctionne. Les autres indicateurs sont facultatifs.

L’application d’hébergement peut vouloir contrôler certains aspects de l’expérience utilisateur. Par exemple, masquez le volet de connexion ou désactivez la connexion à d’autres clusters. Pour ce scénario, l’explorateur web prend en charge les indicateurs de fonctionnalité.

Un indicateur de fonctionnalité peut être utilisé dans l’URL en tant que paramètre de requête. Pour désactiver l’ajout d’autres clusters, utilisez https://dataexplorer.azure.com/?f-ShowConnectionButtons=false dans l’application d’hébergement.

Paramètre de Description Valeur par défaut
f-ShowShareMenu Afficher l’élément de menu partager true
f-ShowConnectionButtons Afficher le bouton Ajouter une connexion pour ajouter un nouveau cluster true
f-ShowOpenNewWindowButton Afficher le bouton Ouvrir dans l’interface utilisateur web qui ouvre une nouvelle fenêtre de navigateur et pointe vers https://dataexplorer.azure.com avec le cluster et la base de données appropriés dans l’étendue false
f-ShowFileMenu Afficher le menu fichier (télécharger, onglet, contenu, et ainsi de suite) true
f-ShowToS Afficher le lien vers les conditions d’utilisation d’Azure Data Explorer à partir de la boîte de dialogue paramètres true
f-ShowPersona Affichez le nom d’utilisateur dans le menu paramètres, dans le coin supérieur droit. true
f-UseMeControl Afficher les informations du compte de l’utilisateur true
f-IFrameAuth Si la valeur est true, l’explorateur web s’attend à ce que l’iframe gère l’authentification et fournisse un jeton via un message. Ce paramètre est requis pour les scénarios d’iframe. false
f-PersistAfterEachRun En règle générale, les navigateurs persistent dans l’événement de déchargement. Toutefois, l’événement de déchargement n’est pas toujours déclenché lors de l’hébergement dans un iframe. Cet indicateur déclenche l’événement d’état local persistant après chaque exécution de requête. Cela limite toute perte de données qui peut se produire, pour affecter uniquement le nouveau texte de requête qui n’a jamais été exécuté. false
f-ShowSmoothIngestion Si la valeur est true, affichez l’expérience de l’Assistant d’ingestion lorsque vous cliquez avec le bouton droit sur une base de données true
f-RefreshConnection Si la valeur est true, actualise toujours le schéma lors du chargement de la page et ne dépend jamais du stockage local false
f-ShowPageHeader Si la valeur est true, affiche l’en-tête de page qui inclut le titre et les paramètres Azure Data Explorer true
f-HideConnectionPane Si la valeur est true, le volet de connexion de gauche ne s’affiche pas false
f-SkipMonacoFocusOnInit Correction du problème de focus lors de l’hébergement sur iframe false
f-Page d’accueil Activer la page d’accueil et réacheminer les nouveaux utilisateurs vers celle-ci true
f-ShowNavigation Si la valeur est true, affiche le volet de navigation à gauche true
f-DisableDashboardTopBar Si la valeur est true, masque la barre supérieure dans le tableau de bord false
f-DisableNewDashboard Si la valeur est true, masque l’option permettant d’ajouter un nouveau tableau de bord false
f-DisableNewDashboard Si la valeur est true, masque l’option de recherche dans la liste des tableaux de bord false
f-DisableDashboardEditMenu Si la valeur est true, masque l’option permettant de modifier un tableau de bord false
f-DisableDashboardFileMenu SI la valeur est true, masque le bouton de menu Fichier dans un tableau de bord false
f-DisableDashboardShareMenu Si la valeur est true, masque le bouton de menu Partager dans un tableau de bord false
f-DisableDashboardDelete Si la valeur est true, masque le bouton supprimer du tableau de bord false
f-DisableTileRefresh SI la valeur est true, désactive le bouton d’actualisation des vignettes dans un tableau de bord false
f-DisableDashboardAutoRefresh SI la valeur est true, désactive l’actualisation automatique des vignettes dans un tableau de bord false
f-DisableExploreQuery Si la valeur est true, désactive le bouton explorer la requête des vignettes false
f-DisableCrossFiltering SI la valeur est true, désactive la fonctionnalité de filtrage croisé dans les tableaux de bord false
f-HideDashboardParametersBar SI la valeur est true, masque la barre de paramètres dans un tableau de bord false

Contenu connexe