Vložení webového uživatelského rozhraní Azure Data Explorer do prvku iframe

Článek
06/15/2023

Webové uživatelské rozhraní Azure Data Explorer je možné vložit do prvku iframe a hostovat ho na webech třetích stran. Tento článek popisuje, jak vložit webové uživatelské rozhraní Azure Data Explorer do prvku iframe.

Snímek obrazovky s webovým uživatelským rozhraním Azure Data Explorer

Všechny funkce jsou testovány z hlediska přístupnosti a podporují tmavé a světlé motivy na obrazovce.

Jak vložit webové uživatelské rozhraní do prvku iframe

Na web přidejte následující kód:

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

Parametr f-IFrameAuth dotazu říká webovému uživatelskému rozhraní, aby nepřesměrovává, aby získalo ověřovací token, a f-UseMeControl=false parametr říká webovému uživatelskému rozhraní, aby nezobrazil automaticky otevírané okno s informacemi o uživatelském účtu. Tyto akce jsou nezbytné, protože hostující web zodpovídá za ověřování.

Parametr workspace=<guid> dotazu vytvoří samostatný pracovní prostor pro vložený prvek iframe. Pracovní prostor je jednotka logiky, která obsahuje karty, dotazy, nastavení a připojení. Nastavením na jedinečnou hodnotu zabrání sdílení dat mezi vloženou a neveřenou verzí nástroje https://dataexplorer.azure.com.

Zpracování ověřování

Při vkládání webového uživatelského rozhraní zodpovídá za ověřování hostitelská stránka. Následující diagramy popisují tok ověřování.

Ověřování můžete zpracovat pomocí následujících kroků:

V aplikaci poslouchejte zprávu 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
   }
})

Definujte funkci pro mapování event.data.scope oboru na Microsoft Entra. V následující tabulce se můžete rozhodnout, jak namapovat event.data.scope obory Microsoft Entra:

Prostředek	event.data.scope	Microsoft Entra rozsah
Cluster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Graph	`People.Read`	`People.Read`, `User.ReadBasic.All`, `Group.Read.All`
Řídicí panely	`https://rtd-metadata.azurewebsites.net/user_impersonation`	`https://rtd-metadata.azurewebsites.net/user_impersonation`

Například následující funkce mapuje obory na základě informací v tabulce.

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

Získejte přístupový token JWT z koncového bodu ověřování Microsoft Entra pro obor. Tento kód nahrazuje zástupný kód CODE-1.

Můžete například použít @azure/MSAL-react k získání přístupového tokenu. Příklad používá funkci mapScope , kterou jste definovali dříve.
```
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
)
```
Důležité

K ověřování můžete použít jenom hlavní název uživatele (UPN), instanční objekty se nepodporují.
Publikujte zprávu postToken s přístupovým tokenem. Tento kód nahradí zástupný kód CODE-2:
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, '*');
   }
```
Důležité

Hostitelské okno musí token před vypršením platnosti aktualizovat odesláním nové zprávy postToken s aktualizovanými tokeny. V opačném případě se po vypršení platnosti tokenů volání služby nezdaří.

Tip

V našem ukázkovém projektu můžete zobrazit aplikaci , která používá ověřování.

Vložení řídicích panelů

Pokud chcete vložit řídicí panel, je nutné vytvořit vztah důvěryhodnosti mezi aplikací Microsoft Entra hostitele a službou řídicího panelu Azure Data Explorer (RTD Metadata Service).

Postupujte podle pokynů v tématu Ověřování a autorizace webového klienta (JavaScript).
Otevřete Azure Portal a ujistěte se, že jste přihlášení ke správnému tenantovi. V pravém horním rohu ověřte identitu používanou k přihlášení k portálu.
V podokně prostředků vyberte ID> Microsoft Entra Registrace aplikací.
Vyhledejte aplikaci, která používá tok on-behalf-of , a otevřete ji.
Vyberte Manifest.
Vyberte requiredResourceAccess.
Do manifestu přidejte následující položku:
```
  {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 35e917a9-4d95-4062-9d97-5781291353b9je ID aplikace služby řídicího panelu Azure Data Explorer.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c je oprávnění user_impersonation.
V manifestu uložte změny.
Vyberte Oprávnění rozhraní API a ověřte, že máte novou položku: Služba metadat RTD.
V části Microsoft Graph přidejte oprávnění pro People.Read, User.ReadBasic.Alla Group.Read.All.
V Azure PowerShell přidejte pro aplikaci následující nový instanční objekt:
```
New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
```
Pokud narazíte na Request_MultipleObjectsWithSameKeyValue chybu, znamená to, že aplikace už je v tenantovi, což značí, že se úspěšně přidala.
Na stránce Oprávnění rozhraní API vyberte Udělit souhlas správce se souhlasem pro všechny uživatele.

Poznámka

Pokud chcete vložit řídicí panel bez oblasti dotazu, použijte následující nastavení:

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

kde [feature-flags] je:

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

Příznaky funkcí

Důležité

Aby f-IFrameAuth=true prvek iframe fungoval, vyžaduje se příznak. Ostatní příznaky jsou volitelné.

Hostitelská aplikace může chtít řídit určité aspekty uživatelského prostředí. Můžete například skrýt podokno připojení nebo zakázat připojení k jiným clusterům. Pro tento scénář webový průzkumník podporuje příznaky funkcí.

Příznak funkce lze v adrese URL použít jako parametr dotazu. Pokud chcete zakázat přidávání dalších clusterů, použijte https://dataexplorer.azure.com/?f-ShowConnectionButtons=false v hostitelské aplikaci.

Nastavení	Description	Výchozí hodnota
f-ShowShareMenu	Zobrazení položky nabídky sdílení	true
f-ShowConnectionButtons	Zobrazení tlačítka přidat připojení pro přidání nového clusteru	true
f-ShowOpenNewWindowButton	Zobrazení tlačítka Otevřít ve webovém uživatelském rozhraní, které otevře nové okno prohlížeče a odkazuje na https://dataexplorer.azure.com správný cluster a databázi v oboru	false (nepravda)
f-ShowFileMenu	Zobrazení nabídky souborů (stažení, karta, obsah atd.)	true
f-ShowToS	Zobrazit odkaz na podmínky služby pro Azure Data Explorer v dialogovém okně nastavení	true
f-ShowPersona	Zobrazí uživatelské jméno z nabídky nastavení v pravém horním rohu.	true
f-UseMeControl	Zobrazení informací o účtu uživatele	true
f-IFrameAuth	Pokud je true, webový průzkumník očekává, že iframe zpracuje ověřování a poskytne token prostřednictvím zprávy. Tento parametr se vyžaduje pro scénáře iframe.	false (nepravda)
f-PersistAfterEachRun	Prohlížeče obvykle zůstávají v události uvolnění. Událost uvolnění se ale neaktivuje vždy při hostování v prvku iframe. Tento příznak aktivuje událost místního stavu po každém spuštění dotazu. Tím se omezí případná ztráta dat a ovlivní to jenom text nového dotazu, který se nikdy nespustí.	false (nepravda)
f-ShowSmoothIngestion	Pokud je hodnota true, zobrazí se při kliknutí pravým tlačítkem myši na databázi průvodce příjmem dat.	true
f-RefreshConnection	Pokud je true, vždy aktualizuje schéma při načítání stránky a nikdy nezávisí na místním úložišti.	false (nepravda)
f-ShowPageHeader	Pokud je true, zobrazí záhlaví stránky, které obsahuje název a nastavení azure Data Explorer.	true
f-HideConnectionPane	Pokud je hodnota true, levé podokno připojení se nezobrazuje.	false (nepravda)
f-SkipMonacoFocusOnInit	Opravuje problém s fokusem při hostování v elementu iframe.	false (nepravda)
f-Domovská stránka	Povolení domovské stránky a přesměrování nových uživatelů na ni	true
f-ShowNavigation	POKUD je true, zobrazuje navigační podokno na levé straně.	true
f-DisableDashboardTopBar	Pokud je true, skryje horní panel na řídicím panelu.	false (nepravda)
f-DisableNewDashboard	POKUD je true, skryje možnost pro přidání nového řídicího panelu.	false (nepravda)
f-DisableNewDashboard	POKUD je true, skryje možnost hledání v seznamu řídicích panelů.	false (nepravda)
f-DisableDashboardEditMenu	POKUD je true, skryje možnost pro úpravu řídicího panelu.	false (nepravda)
f-DisableDashboardFileMenu	Pokud je true, skryje tlačítko nabídky Soubor na řídicím panelu.	false (nepravda)
f-DisableDashboardShareMenu	Pokud je true, skryje tlačítko nabídky sdílení na řídicím panelu.	false (nepravda)
f-DisableDashboardDelete	Pokud je true, skryje tlačítko pro odstranění řídicího panelu.	false (nepravda)
f-DisableTileRefresh	POKUD je true, zakáže dlaždice tlačítko aktualizovat na řídicím panelu.	false (nepravda)
f-DisableDashboardAutoRefresh	POKUD je true, zakáže automatickou aktualizaci dlaždic na řídicím panelu.	false (nepravda)
f-DisableExploreQuery	POKUD je true, zakáže tlačítko prozkoumat dotaz na dlaždicích.	false (nepravda)
f-DisableCrossFiltering	POKUD je true, zakáže funkci křížového filtrování na řídicích panelech.	false (nepravda)
f-HideDashboardParametersBar	POKUD je true, skryje panel parametrů na řídicím panelu.	false (nepravda)

Share via

Vložení webového uživatelského rozhraní Azure Data Explorer do prvku iframe

Jak vložit webové uživatelské rozhraní do prvku iframe

Zpracování ověřování

Vložení řídicích panelů

Příznaky funkcí

Váš názor

Váš názor

Další materiály

Share via

Vložení webového uživatelského rozhraní Azure Data Explorer do prvku iframe

Jak vložit webové uživatelské rozhraní do prvku iframe

Zpracování ověřování

Vložení řídicích panelů

Příznaky funkcí

Související obsah

Váš názor

Váš názor

Další materiály