Incorporare l'interfaccia utente Web di Azure Esplora dati in un iframe

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

L'interfaccia utente Web di Azure Esplora dati può essere incorporata in un iframe e ospitata in siti Web di terze parti. Questo articolo descrive come incorporare l'interfaccia utente Web di Azure Esplora dati in un iframe.

Tutte le funzionalità vengono testate per l'accessibilità e supportano temi sullo schermo scuri e chiari.

Come incorporare l'interfaccia utente Web in un iframe

Aggiungere il codice seguente al sito Web:

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

Il f-IFrameAuth parametro di query indica all'interfaccia utente Web di non reindirizzare per ottenere un token di autenticazione e il f-UseMeControl=false parametro indica all'interfaccia utente Web di non visualizzare la finestra popup informazioni sull'account utente. Queste azioni sono necessarie perché il sito Web di hosting è responsabile dell'autenticazione.

Il workspace=<guid> parametro di query crea un'area di lavoro separata per l'iframe incorporato. L'area di lavoro è un'unità logica che contiene schede, query, impostazioni e connessioni. Impostandolo su un valore univoco, impedisce la condivisione dei dati tra la versione incorporata e quella non incorporata di https://dataexplorer.azure.com.

Gestire l'autenticazione

Quando si incorpora l'interfaccia utente Web, la pagina di hosting è responsabile dell'autenticazione. I diagrammi seguenti descrivono il flusso di autenticazione.

Per gestire l'autenticazione, seguire questa procedura:

1. Nell'applicazione restare in ascolto del messaggio 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. Definire una funzione per eseguire il mapping dell'oggetto all'ambito event.data.scope di Microsoft Entra. Usare la tabella seguente per decidere come eseguire il mapping event.data.scope agli ambiti di Microsoft Entra:

   Conto risorse	event.data.scope	Ambito di Microsoft Entra
   Cluster	query	https://{your_cluster}.{your_region}.kusto.windows.net/.default
   Grafico	People.Read	People.Read, User.ReadBasic.All, Group.Read.All
   Dashboard	https://rtd-metadata.azurewebsites.net/user_impersonation	https://rtd-metadata.azurewebsites.net/user_impersonation

   Ad esempio, la funzione seguente esegue il mapping degli ambiti in base alle informazioni nella tabella.

       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. Ottenere un token di accesso JWT dall'autenticazione Esegui applicazione a pagina singola (SPA) per l'ambito. Questo codice sostituisce il segnaposto CODE-1.

   Ad esempio, è possibile usare @azure/MSAL-react per ottenere il token di accesso. Nell'esempio viene usata la funzione mapScope definita in precedenza.

   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

   È possibile usare solo il nome dell'entità utente (UPN) per l'autenticazione, le entità servizio non sono supportate.

4. Pubblicare un messaggio postToken con il token di accesso. Questo codice sostituisce il segnaposto 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 finestra di hosting deve aggiornare il token prima della scadenza inviando un nuovo messaggio postToken con token aggiornati. In caso contrario, una volta scaduti i token, le chiamate al servizio avranno esito negativo.

Incorporare dashboard

Per incorporare un dashboard, è necessario stabilire una relazione di trust tra l'app Microsoft Entra dell'host e il servizio dashboard di Azure Esplora dati (RTD Metadata Service).

1. Seguire la procedura descritta in Eseguire l'autenticazione a pagina singola (SPA).

2. Aprire il portale di Azure e assicurarsi di aver eseguito l'accesso al tenant corretto. Nell'angolo superiore destro verificare l'identità usata per accedere al portale.

3. Nel riquadro delle risorse selezionare Microsoft Entra ID> Registrazioni app.

4. Individuare l'app che usa il flusso on-behalf-of e aprirla.

5. Selezionare Manifesto.

6. Selezionare RequiredResourceAccess.

7. Nel manifesto aggiungere la voce seguente:

     {
       "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
       "resourceAccess": [
           {
               "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
               "type": "Scope"
           }
       ]
     }
   

   • 00001111-aaaa-2222-bbbb-3333cccc4444è l'ID applicazione del servizio dashboard di Azure Esplora dati.
   • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c è l'autorizzazione user_impersonation.

8. Nel manifesto salvare le modifiche.

9. Selezionare Autorizzazioni API e verificare di avere una nuova voce: Servizio metadati RTD.

10. In Microsoft Graph aggiungere autorizzazioni per People.Read, User.ReadBasic.Alle Group.Read.All.

11. In Azure PowerShell aggiungere la nuova entità servizio seguente per l'app:

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

    Se si verifica l'errore Request_MultipleObjectsWithSameKeyValue , significa che l'app si trova già nel tenant che indica che è stata aggiunta correttamente.

12. Nella pagina Autorizzazioni API selezionare Concedi consenso amministratore per il consenso per tutti gli utenti.

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

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

Flag di funzionalità

L'app di hosting può voler controllare determinati aspetti dell'esperienza utente. Ad esempio, nascondere il riquadro di connessione o disabilitare la connessione ad altri cluster. Per questo scenario, Esplora Web supporta i flag di funzionalità.

Un flag di funzionalità può essere usato nell'URL come parametro di query. Per disabilitare l'aggiunta di altri cluster, usare https://dataexplorer.azure.com/?f-ShowConnectionButtons=false nell'app di hosting.

Contenuto correlato

• Panoramica di Linguaggio di query Kusto (KQL)
• Scrivere query Kusto
• Esempio di incorporamento