Osadź internetowy interfejs użytkownika usługi Azure Data Explorer w elemencie iframe

2025-06-22

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Internetowy Interfejs Użytkownika usługi Azure Data Explorer można osadzać w ramce iframe i umieszczać na stronach internetowych innych firm. W tym artykule opisano sposób osadzania internetowego interfejsu użytkownika usługi Azure Data Explorer w elemecie iframe.

Zrzut ekranu przedstawiający webowy interfejs użytkownika usługi Azure Data Explorer.

Wszystkie funkcje są testowane pod kątem ułatwień dostępu i obsługują motywy ciemne i jasne na ekranie.

Jak osadzić internetowy interfejs użytkownika w elemecie iframe

Dodaj następujący kod do witryny internetowej:

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

f-IFrameAuth Parametr zapytania informuje interfejs internetowy użytkownika, aby nie przekierowywał użytkownika w celu uzyskania tokenu uwierzytelniania, a parametr f-UseMeControl=false informuje go, aby nie wyświetlał okna podręcznego z informacjami o koncie. Te działania są niezbędne, ponieważ witryna internetowa hostingu jest odpowiedzialna za uwierzytelnianie.

Parametr workspace=<guid> zapytania tworzy oddzielny obszar roboczy dla osadzonego elementu iframe. Obszar roboczy to jednostka logiki zawierająca karty, zapytania, ustawienia i połączenia. Ustawiając ją na unikatową wartość, zapobiega się udostępnianiu danych między osadzoną a nieosadzoną wersją programu https://dataexplorer.azure.com.

Obsługa uwierzytelniania

Podczas osadzania internetowego interfejsu użytkownika strona hostingu jest odpowiedzialna za uwierzytelnianie. Na poniższych diagramach opisano przepływ uwierzytelniania.

Aby obsłużyć uwierzytelnianie, wykonaj następujące czynności:

W aplikacji nasłuchuj komunikatu getToken .

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

Zdefiniuj funkcję mapowania event.data.scope na zakres Microsoft Entra. Skorzystaj z poniższej tabeli, aby zdecydować, jak mapować event.data.scope na zakresy Microsoft Entra.

Zasób	event.data.scope	Zakres Microsoft Entra
Klaster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Wykres	`People.Read`	`People.Read`, , `User.ReadBasic.AllGroup.Read.All`
Pulpity nawigacyjne	`https://rtd-metadata.azurewebsites.net/user_impersonation`	`https://rtd-metadata.azurewebsites.net/user_impersonation`

Na przykład poniższa funkcja mapuje zakresy na podstawie informacji w tabeli.

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

Pobierz token dostępu JWT z wykonania uwierzytelniania aplikacji jednostronicowej (SPA) w ramach zakresu. Ten kod zastępuje symbol zastępczy CODE-1.

Na przykład możesz użyć @azure/MSAL-react, aby uzyskać token dostępu. W przykładzie użyto zdefiniowanej wcześniej funkcji mapScope .
```
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
)
```
Ważne

Można używać tylko Nazwy Głównej Użytkownika (UPN) do uwierzytelniania, natomiast jednostki usługi nie są obsługiwane.
Opublikuj komunikat postToken z tokenem dostępu. Ten kod zastępuje symbol zastępczy 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'); 
   }
```
Ważne

Okno hostingu musi odświeżyć token przed wygaśnięciem, wysyłając nowy komunikat postToken ze zaktualizowanymi tokenami. W przeciwnym razie po wygaśnięciu tokenów wywołania usługi zakończy się niepowodzeniem.

Napiwek

W naszym przykładowym projekcie możesz wyświetlić aplikację korzystającą z uwierzytelniania.

Osadź pulpity nawigacyjne

Aby osadzić pulpit nawigacyjny, należy ustanowić relację zaufania między aplikacją Microsoft Entra hosta a usługą Azure Data Explorer (RTD Metadata Service).

Postępuj zgodnie z krokami opisanymi w Uwierzytelnianiu aplikacji jednostronicowej (SPA).
Otwórz portal Azure i upewnij się, że jesteś zalogowany do właściwej dzierżawy. W prawym górnym rogu sprawdź tożsamość używaną do logowania się do portalu.
W okienku zasobów wybierz pozycję Microsoft Entra ID> Rejestracje aplikacji.
Znajdź aplikację, która używa przepływu w imieniu i otwórz ją.
Wybierz pozycję Manifest.
Wybierz requiredResourceAccess.
W manifeście dodaj następujący wpis:
```
  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 00001111-aaaa-2222-bbbb-3333cccc4444 to identyfikator aplikacji usługi pulpitu nawigacyjnego usługi Azure Data Explorer.
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c to uprawnienie user_impersonation.
W manifeście zapisz zmiany.
Wybierz Uprawnienia interfejsu API i sprawdź, czy masz nowy wpis: RTD Metadata Service.
W programie Microsoft Graph dodaj uprawnienia dla People.Read, User.ReadBasic.Alli Group.Read.All.
W programie Azure PowerShell dodaj następującą nową jednostkę usługi dla aplikacji:
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
Jeśli wystąpi błąd Request_MultipleObjectsWithSameKeyValue, oznacza to, że aplikacja jest już w dzierżawie, co wskazuje, że została pomyślnie dodana.
Na stronie uprawnień interfejsu API wybierz Udziel zgody administratora dla wszystkich użytkowników.

Uwaga

Aby osadzić pulpit nawigacyjny bez obszaru zapytania, użyj następującej konfiguracji:

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

gdzie [feature-flags] to:

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

Flagi funkcji

Ważne

f-IFrameAuth=true Flaga jest wymagana, aby element iframe działał. Inne flagi są opcjonalne.

Aplikacja hostingowa może chcieć kontrolować niektóre aspekty środowiska użytkownika. Na przykład ukryj okienko połączenia lub wyłącz nawiązywanie połączenia z innymi klastrami. W tym scenariuszu eksplorator sieci Web obsługuje flagi funkcji.

Flaga funkcji może być używana w adresie URL jako parametr zapytania. Aby wyłączyć dodawanie innych klastrów, użyj polecenia https://dataexplorer.azure.com/?f-ShowConnectionButtons=false w aplikacji hostingu.

ustawienie	opis	Wartość domyślna
f-PokażMenuUdostępniania	Pokaż element menu udostępniania	prawda
Given the typical convention of keeping such function names untranslated, no changes are needed.	Pokaż przycisk Dodaj połączenie, aby dodać nowy klaster	prawda
f-PokażPrzyciskOtwórzNoweOkno	Pokaż przycisk interfejsu użytkownika Otwórz w przeglądarce, który otwiera nowe okno przeglądarki i wskazuje na https://dataexplorer.azure.com odpowiedni klaster i bazę danych.	fałsz
f-ShowFileMenu	Pokaż menu pliku (pobieranie, karta, zawartość itd.)	prawda
f-ShowToS	Pokaż link do warunków świadczenia usługi dla usługi Azure Data Explorer w oknie dialogowym ustawień	prawda
f-PokażOsobowość	Pokaż nazwę użytkownika z menu ustawień w prawym górnym rogu.	prawda
f-UseMeControl	Wyświetlanie informacji o koncie użytkownika	prawda
Uwierzytelnianie f-IFrameAuth	Jeśli to prawda, eksplorator sieci Web oczekuje, że element iframe będzie obsługiwał uwierzytelnianie i dostarcza token za pośrednictwem komunikatu. Ten parametr jest wymagany w scenariuszach elementu iframe.	fałsz
f-PersistAfterEachRun	Zazwyczaj przeglądarki utrzymują się w zdarzeniu wyładunku. Jednak zdarzenie 'unload' nie zawsze jest wyzwalane podczas hostowania w elemencie iframe. Ta flaga wyzwala zdarzenie utrwalania stanu lokalnego po każdym uruchomieniu zapytania. Ogranicza to wszelkie możliwe utraty danych, aby dotyczyły tylko nowego tekstu zapytania, który nigdy wcześniej nie był uruchamiany.	fałsz
f-PokażPłynneSpożycie	Jeśli to prawda, wyświetl interfejs kreatora importu po kliknięciu prawym przyciskiem myszy na bazie danych.	prawda
f-OdświeżPołączenie	Jeśli to prawda, zawsze odświeża schemat podczas ładowania strony i nigdy nie zależy od pamięci lokalnej.	fałsz
f-PokażNagłówekStrony	Jeśli ma wartość true, zostanie wyświetlony nagłówek strony zawierający tytuł i ustawienia usługi Azure Data Explorer	prawda
f-UkryjPanelPołączeń	Jeśli ma wartość true, okienko połączenia po lewej stronie nie jest wyświetlane	fałsz
f-SkipMonacoFocusOnInit	Rozwiązuje problem z fokusem podczas hostingu na elemencie iframe	fałsz
Strona główna	Włączanie strony głównej i przekierowywanie nowych użytkowników do niej	prawda
f-PokażNawigację	Jeśli warunek true jest spełniony, pokazuje panel nawigacji po lewej stronie	prawda
f-DisableDashboardTopBar	Jeśli ustawisz na 'true', ukryj górny pasek na pulpicie nawigacyjnym	fałsz
f-WyłączNowyPulpit nawigacyjny	Jeśli to prawda, ukrywa opcję dodawania nowego pulpitu nawigacyjnego	fałsz
f-WyłączMenuEdycjiPulpitu	Jeśli to prawda, ukrywa opcję edytowania pulpitu nawigacyjnego	fałsz
WyłączMenuPlikówNaPulpicie	Jeśli jest prawdą, ukrywa przycisk menu pliku w pulpicie nawigacyjnym.	fałsz
f-WyłączMenuUdostępnianiaKokpitu	Jeśli jest ustawione na wartość true, ukrywa przycisk menu udostępniania na pulpicie nawigacyjnym	fałsz
f-WyłączUsuwaniePanelu	Jeśli wartość jest true, ukrywa przycisk usuwania pulpitu nawigacyjnego	fałsz
Wyłącz Odświeżanie Kafelków	Jeśli true, wyłącza przycisk odświeżania kafelków na panelu nawigacyjnym	fałsz
f-DisableDashboardAutoRefresh	Jeśli prawda, wyłącza automatyczne odświeżanie kafelków na panelu.	fałsz
f-DisableExploreQuery	Jeżeli prawda, wyłącza przycisk eksploracji zapytań elementów	fałsz
Wyłącz CrossFiltering	Jeśli wartość to true, wyłącza funkcję filtrowania krzyżowego na dashboardach	fałsz
f-UkryjPasekParametrówDashboardu	Jeśli true, ukrywa pasek parametrów na panelu sterowania	fałsz

Udostępnij za pośrednictwem

Osadź internetowy interfejs użytkownika usługi Azure Data Explorer w elemencie iframe

Jak osadzić internetowy interfejs użytkownika w elemecie iframe

Obsługa uwierzytelniania

Osadź pulpity nawigacyjne

Flagi funkcji

Powiązana zawartość

Opinia

Dodatkowe zasoby