Einbetten der Azure Data Explorer-Web-UI in ein iframe

Artikel
03/23/2025

Gilt für: ✅Microsoft Fabric ✅Azure Data Explorer

Die Azure Data Explorer-Webbenutzeroberfläche kann in einen iframe eingebettet und auf Websites von Drittanbietern gehostet werden. In diesem Artikel wird beschrieben, wie Sie die Azure Data Explorer-Webbenutzeroberfläche in ein iframe einbetten.

Screenshot des Azure Data Explorer Web U I.

Alle Funktionen werden auf Barrierefreiheit getestet und unterstützen dunkle und helle Designs auf dem Bildschirm.

So betten Sie die Web-UI in ein iframe ein

Fügen Sie Ihrer Website den folgenden Code hinzu:

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

Der Abfrageparameter f-IFrameAuth weist die Webbenutzeroberfläche an, kein Authentifizierungstoken abzurufen, und der Parameter f-UseMeControl=false weist die Webbenutzeroberfläche an, das Popupfenster für Benutzerkontoinformationen nicht anzuzeigen. Diese Aktionen sind erforderlich, da die Hostingwebsite für die Authentifizierung verantwortlich ist.

Der workspace=<guid> Abfrageparameter erstellt einen separaten Arbeitsbereich für den eingebetteten iframe. Der Arbeitsbereich ist eine Logikeinheit, die Registerkarten, Abfragen, Einstellungen und Verbindungen enthält. Wenn er auf einen eindeutigen Wert festgelegt wird, verhindert er die Datenfreigabe zwischen der eingebetteten und der nicht eingebetteten Version von https://dataexplorer.azure.com.

Behandeln der Authentifizierung

Beim Einbetten der Web-UI ist die Hostingseite für die Authentifizierung verantwortlich. Die folgenden Diagramme beschreiben den Authentifizierungsfluss.

Führen Sie die folgenden Schritte aus, um die Authentifizierung zu behandeln:

Lauschen Sie in Ihrer Anwendung auf die getToken-Nachricht .

window.addEventListener('message', (event) => {
   if (event.origin === "https://dataexplorer.azure.com" && 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
   }
})

Definieren Sie eine Funktion, um den event.data.scope Microsoft Entra-Bereich zuzuordnen. Verwenden Sie die folgende Tabelle, um zu entscheiden, wie event.data.scope Microsoft Entra-Bereichen zugeordnet wird.

Ressource	event.data.scope	Microsoft Entra-Bereich
Cluster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Graph	`People.Read`	`People.Read`, `User.ReadBasic.AllGroup.Read.All`
Dashboards	`https://rtd-metadata.azurewebsites.net/user_impersonation`	`https://rtd-metadata.azurewebsites.net/user_impersonation`

Die folgende Funktion ordnet z. B. Bereiche basierend auf den Informationen in der Tabelle zu.

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

Rufen Sie ein JWT-Zugriffstoken aus Durchführen der SPA-Authentifizierung (Single Page Application) für den Bereich ab. Dieser Code ersetzt Platzhalter CODE-1.

Sie können beispielsweise @azure/MSAL-react verwenden, um das Zugriffstoken abzurufen. Im Beispiel wird die zuvor definierte mapScope-Funktion verwendet.
```
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
)
```
Wichtig

Sie können den Benutzerprinzipalnamen (User Principal Name, UPN) nur für die Authentifizierung verwenden, Dienstprinzipale werden nicht unterstützt.
Posten Sie eine postToken-Nachricht mit dem Zugriffstoken . Dieser Code ersetzt Platzhalter CODE-2:
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, 'https://dataexplorer.azure.com'); 
   }
```
Wichtig

Das Hostingfenster muss das Token vor dem Ablauf aktualisieren, indem eine neue postToken-Nachricht mit aktualisierten Token gesendet wird. Andernfalls schlägt der Dienstaufruf fehl, sobald die Token ablaufen.

Tipp

In unserem Beispielprojekt können Sie eine Anwendung anzeigen, die die Authentifizierung verwendet.

Einbetten von Dashboards

Zum Einbetten eines Dashboards muss eine Vertrauensstellung zwischen der Microsoft Entra-App des Hosts und dem Azure Data Explorer-Dashboarddienst (RTD Metadata Service) eingerichtet werden.

Führen Sie die Schritte in Durchführen der SPA-Authentifizierung (Single Page Application) aus.
Öffnen Sie die Azure-Portal, und stellen Sie sicher, dass Sie beim richtigen Mandanten angemeldet sind. Überprüfen Sie in der oberen rechten Ecke die Identität, die zum Anmelden beim Portal verwendet wird.
Wählen Sie im Ressourcenbereich Microsoft Entra ID>App-Registrierungen aus.
Suchen Sie die App, die den On-Behalf-Of-Fluss verwendet, und öffnen Sie sie.
Wählen Sie "Manifest" aus.
Wählen Sie "requiredResourceAccess" aus.
Fügen Sie im Manifest den folgenden Eintrag hinzu:
```
  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 00001111-aaaa-2222-bbbb-3333cccc4444 ist die Anwendungs-ID des Azure Data Explorer-Dashboarddiensts.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c ist die user_impersonation-Berechtigung.
Speichern Sie ihre Änderungen im Manifest.
Wählen Sie API-Berechtigungen aus, und überprüfen Sie, ob Sie einen neuen Eintrag haben: RTD-Metadatendienst.
Fügen Sie unter Microsoft Graph Berechtigungen für People.Read, User.ReadBasic.Allund Group.Read.All.
Fügen Sie in Azure PowerShell den folgenden neuen Dienstprinzipal für die App hinzu:
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
Wenn der Fehler Request_MultipleObjectsWithSameKeyValue auftritt, bedeutet dies, dass sich die App bereits im Mandanten befindet, der angibt, dass sie erfolgreich hinzugefügt wurde.
Wählen Sie auf der Seite "API-Berechtigungen " die Option "Administratorzustimmung erteilen" aus, um allen Benutzern zuzustimmen .

Hinweis

Verwenden Sie zum Einbetten eines Dashboards ohne den Abfragebereich das folgende Setup:

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

wobei [feature-flags] ist:

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

Featureflags

Wichtig

Das f-IFrameAuth=true Kennzeichen ist erforderlich, damit der iframe funktioniert. Die anderen Flags sind optional.

Die Hosting-App möchte möglicherweise bestimmte Aspekte der Benutzererfahrung steuern. Blenden Sie beispielsweise den Verbindungsbereich aus, oder deaktivieren Sie die Verbindung mit anderen Clustern. In diesem Szenario unterstützt der Web Explorer Featurekennzeichnungen.

Ein Feature-Flag kann in der URL als Abfrageparameter verwendet werden. Verwenden Sie zum Deaktivieren des Hinzufügens anderer Cluster https://dataexplorer.azure.com/?f-ShowConnectionButtons=false in der Hosting-App.

Einstellung	Beschreibung	Standardwert
f-ShowShareMenu	Anzeigen des Menüelements „Freigeben“	true
f-ShowConnectionButtons	Anzeigen der Schaltfläche "Verbindung hinzufügen" zum Hinzufügen eines neuen Clusters	true
f-ShowOpenNewWindowButton	Anzeigen der Schaltfläche In Webbenutzeroberfläche öffnen, die ein neues Browserfenster öffnet und auf https://dataexplorer.azure.com mir dem richtigen Cluster und der richtigen Datenbank im Bereich zeigt	false
f-ShowFileMenu	Anzeigen des Menüs „Datei“ (Download, Registerkarte, Inhalt usw.)	true
f-ShowToS	Link zu den Nutzungsbedingungen für Azure Data Explorer im Einstellungsdialogfeld anzeigen	true
f-ShowPersona	Zeigen Sie den Benutzernamen aus dem Menü "Einstellungen" in der oberen rechten Ecke an.	true
f-UseMeControl	Anzeigen der Kontoinformationen des Benutzers	wahr
f-IFrameAuth	Wenn true, erwartet der Web-Explorer, dass der iframe die Authentifizierung verarbeitet und ein Token über eine Nachricht bereitstellt. Dieser Parameter ist für iframe-Szenarien erforderlich.	false
f-PersistAfterEachRun	Normalerweise bleiben Browser während des Entlade-Ereignisses aktiv. Das Unload-Ereignis wird jedoch nicht immer ausgelöst, wenn es in einem iframe gehostet wird. Dieses Flag löst das Ereignis lokalen Zustand beibehalten nach jeder Abfrageausführung aus. Dies beschränkt alle Datenverluste, die auftreten können, um nur neuen Abfragetext zu beeinflussen, der nie ausgeführt wurde.	falsch
f-ShowSmoothIngestion	Wenn „true“, wird die Oberfläche des Aufnahme-Assistenten angezeigt, wenn mit der rechten Maustaste auf eine Datenbank geklickt wird.	wahr
f-RefreshConnection	Wenn „true“, aktualisiert beim Laden der Seite immer das Schema und hängt nie vom lokalen Speicher ab.	falsch
f-ShowPageHeader	Wenn wahr, zeigt die Seitenkopfzeile, die den Titel und die Einstellungen des Azure-Daten-Explorers enthält.	wahr
f-HideConnectionPane	Bei "true" wird der linke Verbindungsbereich nicht angezeigt.	false
f-SkipMonacoFocusOnInit	Behebt das Fokusproblem beim Hosten auf iframe	false
f-Homepage	Aktivieren der Homepage und Umleiten neuer Benutzer an die Startseite	true
f-ShowNavigation	WENN wahr, zeigt den Navigationsbereich auf der linken Seite an.	wahr
f-DisableDashboardTopBar	Wenn wahr, wird die obere Leiste im Dashboard ausgeblendet.	false
f-DisableNewDashboard	WENN wahr, blendet die Option zum Hinzufügen eines neuen Dashboards aus.	false
f-DisableNewDashboard	Wenn „true“, wird die Option zum Suchen in der Dashboardsliste ausgeblendet.	false
f-DisableDashboardEditMenu	WENN wahr, blendet die Option zum Bearbeiten eines Dashboards aus.	false
f-DisableDashboardFileMenu	Wenn auf wahr gesetzt, wird die Menüschaltfläche "Datei" in einem Dashboard ausgeblendet.	false
f-DisableDashboardShareMenu	Wenn „true“, wird die Schaltfläche „Menü freigeben“ in einem Dashboard ausgeblendet.	false
f-DisableDashboardDelete	Wenn „true“, wird die Schaltfläche zum Löschen des Dashboards ausgeblendet.	false
f-DisableTileRefresh	Wenn „true“, wird die Schaltfläche zum Aktualisieren der Kacheln in einem Dashboard deaktiviert.	false
f-DisableDashboardAutoRefresh	WENN wahr, wird die automatische Aktualisierung der Kacheln auf einem Dashboard deaktiviert.	false
f-DisableExploreQuery	Wenn „true“, wird die Schaltfläche „Abfrage durchsuchen“" der Kacheln deaktiviert.	false
f-DisableCrossFiltering	WENN wahr, deaktiviert die Kreuzfilterfunktion in Dashboards.	false
f-HideDashboardParametersBar	Falls wahr, blendet die Parameterleiste in einem Dashboard aus.	falsch

Freigeben über

Einbetten der Azure Data Explorer-Web-UI in ein iframe

So betten Sie die Web-UI in ein iframe ein

Behandeln der Authentifizierung

Einbetten von Dashboards

Featureflags

Feedback

Zusätzliche Ressourcen

Freigeben über

Einbetten der Azure Data Explorer-Web-UI in ein iframe

So betten Sie die Web-UI in ein iframe ein

Behandeln der Authentifizierung

Einbetten von Dashboards

Featureflags

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen