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

Articolo
12/08/2023

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.

Screenshot di Azure Esplora dati Web U I.

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 eseguire il reindirizzamento per ottenere un token di autenticazione e il f-UseMeControl=false parametro indica all'interfaccia utente Web di non visualizzare la finestra popup delle 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:

Nell'applicazione ascoltare il 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
   }
})

Definire una funzione per eseguire il mapping dell'oggetto event.data.scope a Microsoft Entra ambito. Usare la tabella seguente per decidere come eseguire il mapping event.data.scope a Microsoft Entra ambiti:

Risorsa	event.data.scope	ambito 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]
        }
    }

Ottenere un token di accesso JWT dall'endpoint di autenticazione Microsoft Entra 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.
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.

Suggerimento

Nel progetto di esempio è possibile visualizzare un'applicazione che usa l'autenticazione.

Incorporare dashboard

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

Seguire la procedura descritta in Autenticazione e autorizzazione del client Web (JavaScript).
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.
Nel riquadro delle risorse selezionare Microsoft Entra ID>Registrazioni app.
Individuare l'app che usa il flusso on-behalf-of e aprirla.
Selezionare Manifesto.
Selezionare requiredResourceAccess.
Nel manifesto aggiungere la voce seguente:
```
  {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 35e917a9-4d95-4062-9d97-5781291353b9è l'ID applicazione del servizio dashboard di Azure Esplora dati.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c è l'autorizzazione user_impersonation.
Nel manifesto salvare le modifiche.
Selezionare Autorizzazioni API e verificare di avere una nuova voce: Servizio metadati RTD.
In Microsoft Graph aggiungere le autorizzazioni per People.Read, User.ReadBasic.Alle Group.Read.All.
In Azure PowerShell aggiungere la nuova entità servizio seguente per l'app:
```
New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
```
Se si verifica l'errore Request_MultipleObjectsWithSameKeyValue , significa che l'app si trova già nel tenant che indica che è stata aggiunta correttamente.
Nella pagina Autorizzazioni API selezionare Concedi consenso amministratore per il consenso per tutti gli utenti.

Nota

Per incorporare un dashboard senza l'area di query, usare la configurazione seguente:

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

dove [feature-flags] è:

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

Flag di funzionalità

Importante

Il f-IFrameAuth=true flag è necessario per il funzionamento dell'iframe. Gli altri flag sono facoltativi.

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.

impostazione	Descrizione	Valore predefinito
f-ShowShareMenu	Mostra la voce di menu Condividi	true
f-ShowConnectionButtons	Visualizzare il pulsante Aggiungi connessione per aggiungere un nuovo cluster	true
f-ShowOpenNewWindowButton	Mostra il pulsante apri nell'interfaccia utente Web che apre una nuova finestra del browser e punta a https://dataexplorer.azure.com con il cluster e il database corretti nell'ambito	false
f-ShowFileMenu	Visualizzare il menu file (download, scheda, contenuto e così via)	true
f-ShowToS	Visualizzare il collegamento alle condizioni per il servizio per Azure Esplora dati dalla finestra di dialogo delle impostazioni	true
f-ShowPersona	Mostra il nome utente dal menu delle impostazioni, nell'angolo in alto a destra.	true
f-UseMeControl	Visualizzare le informazioni sull'account dell'utente	true
f-IFrameAuth	Se true, Esplora Web prevede che l'iframe gestisca l'autenticazione e fornisca un token tramite un messaggio. Questo parametro è obbligatorio per gli scenari iframe.	false
f-PersistAfterEachRun	In genere, i browser vengono mantenuti nell'evento di scaricamento. Tuttavia, l'evento di scaricamento non viene sempre attivato quando si ospita in un iframe. Questo flag attiva l'evento di stato locale persistente dopo l'esecuzione di ogni query. Questo limita qualsiasi perdita di dati che può verificarsi, per influire solo sul nuovo testo della query che non è mai stato eseguito.	false
f-ShowSmoothIngestion	Se true, visualizzare l'esperienza dell'inserimento guidato quando si fa clic con il pulsante destro del mouse su un database	true
f-RefreshConnection	Se true, aggiorna sempre lo schema durante il caricamento della pagina e non dipende mai dalla risorsa di archiviazione locale	false
f-ShowPageHeader	Se true, mostra l'intestazione di pagina che include il titolo e le impostazioni di Azure Esplora dati	true
f-HideConnectionPane	Se true, il riquadro di connessione a sinistra non viene visualizzato	false
f-SkipMonacoFocusOnInit	Risolve il problema di stato attivo durante l'hosting in iframe	false
f-Homepage	Abilitare la home page e reindirizzarvi nuovi utenti	true
f-ShowNavigation	SE true, mostra il riquadro di spostamento a sinistra	true
f-DisableDashboardTopBar	SE true, nasconde la barra superiore nel dashboard	false
f-DisableNewDashboard	SE true, nasconde l'opzione per aggiungere un nuovo dashboard	false
f-DisableNewDashboard	SE true, nasconde l'opzione per la ricerca nell'elenco dei dashboard	false
f-DisableDashboardEditMenu	SE true, nasconde l'opzione per modificare un dashboard	false
f-DisableDashboardFileMenu	SE true, nasconde il pulsante di menu file in un dashboard	false
f-DisableDashboardShareMenu	SE true, nasconde il pulsante di menu condividi in un dashboard	false
f-DisableDashboardDelete	SE true, nasconde il pulsante di eliminazione del dashboard	false
f-DisableTileRefresh	SE true, disabilita il pulsante di aggiornamento dei riquadri in un dashboard	false
f-DisableDashboardAutoRefresh	SE true, disabilita l'aggiornamento automatico dei riquadri in un dashboard	false
f-DisableExploreQuery	SE true, disabilita il pulsante esplora query dei riquadri	false
f-DisableCrossFiltering	SE true, disabilita la funzionalità di filtro incrociato nei dashboard	false
f-HideDashboardParametersBar	SE true, nasconde la barra dei parametri in un dashboard	false

Condividi tramite

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

Come incorporare l'interfaccia utente Web in un iframe

Gestire l'autenticazione

Incorporare dashboard

Flag di funzionalità

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Come incorporare l'interfaccia utente Web in un iframe

Gestire l'autenticazione

Incorporare dashboard

Flag di funzionalità

Contenuti correlati

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive