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

Article
10/30/2024

S’applique à : ✅Microsoft Fabric ✅Azure Data Explorer

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

Capture d’écran de l’U I web Azure Data Explorer.

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

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 que le f-UseMeControl=false paramètre indique à l’interface utilisateur web de ne pas afficher la fenêtre contextuelle d’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 le définissant sur 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.

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

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
   }
})

Définissez une fonction pour mapper l’étendue event.data.scope Microsoft Entra. Utilisez le tableau suivant pour déterminer comment mapper event.data.scope aux étendues Microsoft Entra :

Ressource	event.data.scope	Étendue Microsoft Entra
Cluster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Graphique	`People.Read`	`People.Read`, , `User.ReadBasic.AllGroup.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 le tableau.

    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]
        }
    }

Obtenez un jeton d’accès JWT à partir de l’authentification d’application monopage (SPA) 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 le nom d’utilisateur principal (UPN) que pour l’authentification, les principaux de service ne sont pas pris en charge.
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 (service de métadonnées RTD).

Suivez les étapes de l’authentification spa (Single Page Application).
Ouvrez le Portail Azure et vérifiez que vous êtes connecté au locataire approprié. Dans le coin supérieur droit, vérifiez l’identité utilisée pour se connecter au portail.
Dans le volet ressources, sélectionnez Inscriptions d’applications d’ID>Microsoft Entra.
Recherchez l’application qui utilise le flux on-behalf-of et ouvrez-la.
Sélectionnez Manifeste.
Sélectionnez requiredResourceAccess.
Dans le manifeste, ajoutez l’entrée suivante :
```
  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 00001111-aaaa-2222-bbbb-3333cccc4444 est l’ID d’application du service de tableau de bord Azure Data Explorer.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c est l’autorisation user_impersonation.
Dans le manifeste, enregistrez vos modifications.
Sélectionnez les autorisations d’API et vérifiez que vous disposez d’une nouvelle entrée : RTD Metadata Service.
Sous Microsoft Graph, ajoutez des autorisations pour People.Read, User.ReadBasic.Allet Group.Read.All.
Dans Azure PowerShell, ajoutez le nouveau principal de service suivant pour l’application :
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
Si vous rencontrez l’erreur Request_MultipleObjectsWithSameKeyValue , cela signifie que l’application se trouve déjà dans le locataire indiquant qu’elle a été ajoutée avec succès.
Dans la page Autorisations de l’API, sélectionnez Accorder le consentement de l’administrateur pour tous les utilisateurs.

Remarque

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 comme paramètre de requête. Pour désactiver l’ajout d’autres clusters, utilisez https://dataexplorer.azure.com/?f-ShowConnectionButtons=false l’application d’hébergement.

setting	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 le cluster et la base de données appropriés dans l’étendue	false
f-ShowFileMenu	Afficher le menu fichier (téléchargement, 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 de 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 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 d’Azure Data Explorer	true
f-HideConnectionPane	Si la valeur est true, le volet de connexion gauche ne s’affiche pas	false
f-SkipMonacoFocusOnInit	Corrige le problème de focus lors de l’hébergement sur iframe	false
f-Page d’accueil	Activer la page d’accueil et le réacheminement des nouveaux utilisateurs vers celui-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 à rechercher 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 des paramètres dans un tableau de bord	false

Partage via

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

Comment incorporer l’interface utilisateur web dans un iframe

Gérer l’authentification

Tableaux de bord incorporés

Indicateurs de fonctionnalités

Commentaires

Ressources supplémentaires

Partage via

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

Comment incorporer l’interface utilisateur web dans un iframe

Gérer l’authentification

Tableaux de bord incorporés

Indicateurs de fonctionnalités

Contenu connexe

Commentaires

Ressources supplémentaires