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

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.

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 f-IFrameAuth Abfrageparameter weist die Webbenutzeroberfläche an, kein Authentifizierungstoken abzurufen, und der f-UseMeControl=false Parameter 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. Arbeitsbereich ist eine Logikeinheit, die Registerkarten, Abfragen, Einstellungen und Verbindungen enthält. Durch Festlegen auf einen eindeutigen Wert verhindert sie 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:

1. Lauschen Sie in Ihrer Anwendung auf die getToken-Nachricht .

   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. Definieren Sie eine Funktion, um den event.data.scope Microsoft Entra-Bereich zuzuordnen. Verwenden Sie die folgende Tabelle, um zu entscheiden, wie Microsoft Entra-Bereiche zugeordnet event.data.scope werden:

   Resource	event.data.scope	Microsoft Entra-Bereich
   Cluster	query	https://{your_cluster}.{your_region}.kusto.windows.net/.default
   Diagramm	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]
           }
       }
   

3. Rufen Sie ein JWT-Zugriffstoken aus der Spa-Authentifizierung (Perform Single Page Application) für den Bereich ab. Dieser Code ersetzt PlatzhalterCODE-1.

   Beispielsweise können @azure/MSAL-react Sie das Zugriffstoken abrufen. 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.

4. Posten Sie eine postToken-Nachricht mit dem Zugriffstoken . Dieser Code ersetzt PlatzhalterCODE-2:

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

   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.

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.

1. Führen Sie die Schritte in der Single Page Application (SPA)-Authentifizierung aus.

2. Ö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.

3. Wählen Sie im Ressourcenbereich die Microsoft Entra-ID> App-Registrierungen aus.

4. Suchen Sie die App, die den Fluss im Auftrag des Unternehmens verwendet, und öffnen Sie sie.

5. Wählen Sie "Manifest" aus.

6. Wählen Sie "requiredResourceAccess" aus.

7. 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.

8. Speichern Sie ihre Änderungen im Manifest.

9. Wählen Sie API-Berechtigungen aus, und überprüfen Sie, ob Sie einen neuen Eintrag haben: RTD-Metadatendienst.

10. Fügen Sie unter Microsoft Graph Berechtigungen für People.Read, User.ReadBasic.Allund Group.Read.All.

11. 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 Request_MultipleObjectsWithSameKeyValue Fehler auftritt, bedeutet dies, dass sich die App bereits im Mandanten befindet, der angibt, dass sie erfolgreich hinzugefügt wurde.

12. Wählen Sie auf der Seite "API-Berechtigungen " die Option "Administratorzustimmung erteilen" aus, um allen Benutzern zuzustimmen .

 <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,

Featureflags

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.

Zugehöriger Inhalt

• Kusto Query Language (KQL) – Übersicht
• Schreiben von Kusto-Abfragen
• Einbetten des Beispiels