Osadzanie internetowego interfejsu użytkownika usługi Azure Data Explorer w elemecie iframe

Artykuł
01/10/2024

Internetowy interfejs użytkownika usługi Azure Data Explorer można osadzać w elementach iframe i hostowanych w witrynach 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 internetowy interfejs użytkownika platformy 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 internetowy interfejs użytkownika, aby nie przekierowywał w celu pobrania tokenu uwierzytelniania, a f-UseMeControl=false parametr informuje internetowy interfejs użytkownika, aby nie wyświetlał okna podręcznego informacji o koncie użytkownika. 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ść, uniemożliwia udostępnianie danych między osadzoną a nie osadzoną 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.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
   }
})

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

Zasób	event.data.scope	zakres Microsoft Entra
Klaster	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
Graph	`People.Read`	`People.Read`, `User.ReadBasic.All`, `Group.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 punktu końcowego uwierzytelniania Microsoft Entra dla zakresu. Ten kod zastępuje symbol zastępczy CODE-1.

Na przykład możesz użyć @azure/MSAL-react polecenia , 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

Do uwierzytelniania można używać tylko głównej nazwy użytkownika (UPN), a 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
     }, '*');
   }
```
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.

Porada

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

Osadzanie pulpitów nawigacyjnych

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

Wykonaj kroki opisane w temacie Uwierzytelnianie i autoryzacja klienta internetowego (JavaScript).
Otwórz Azure Portal i upewnij się, że zalogowano się do odpowiedniej 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 IDENTYFIKATOR>Rejestracje aplikacji.
Znajdź aplikację, która używa przepływu w imieniu i otwórz go.
Wybierz pozycję Manifest.
Wybierz pozycję requiredResourceAccess.
W manifeście dodaj następujący wpis:
```
  {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 35e917a9-4d95-4062-9d97-5781291353b9to 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 pozycję 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 Azure PowerShell dodaj następującą nową jednostkę usługi dla aplikacji:
```
New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
```
Jeśli wystąpi Request_MultipleObjectsWithSameKeyValue błąd, oznacza to, że aplikacja jest już w dzierżawie wskazująca, że została pomyślnie dodana.
Na stronie Uprawnienia interfejsu API wybierz pozycję Udziel zgody administratora na zgodę 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

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

Aplikacja hostingu może chcieć kontrolować pewne 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	Description	Wartość domyślna
f-ShowShareMenu	Pokaż element menu udostępniania	true
f-ShowConnectionButtons	Pokaż przycisk Dodawania połączenia , aby dodać nowy klaster	true
f-ShowOpenNewWindowButton	Pokaż przycisk otwórz w internetowym interfejsie użytkownika, który otwiera nowe okno przeglądarki i wskazuje https://dataexplorer.azure.com odpowiedni klaster i bazę danych w zakresie	fałsz
f-ShowFileMenu	Pokaż menu pliku (pobieranie, karta, zawartość itd.)	true
f-ShowToS	Pokaż link do warunków użytkowania usługi Azure Data Explorer w oknie dialogowym ustawień	true
f-ShowPersona	Pokaż nazwę użytkownika z menu ustawień w prawym górnym rogu.	true
f-UseMeControl	Wyświetlanie informacji o koncie użytkownika	true
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 iframe.	fałsz
f-PersistAfterEachRun	Zazwyczaj przeglądarki są utrwalane w zdarzeniu zwalniania. Jednak zdarzenie zwolnienia nie zawsze jest wyzwalane podczas hostowania w elemecie iframe. Ta flaga wyzwala utrwalające zdarzenie stanu lokalnego po każdym uruchomieniu zapytania. Ogranicza to wszelkie utraty danych, które mogą wystąpić, aby wpływać tylko na nowy tekst zapytania, który nigdy nie został uruchomiony.	fałsz
f-ShowSmoothIngestion	Jeśli to prawda, po kliknięciu prawym przyciskiem myszy bazy danych pokaż środowisko kreatora pozyskiwania	true
f-RefreshConnection	Jeśli to prawda, zawsze odświeża schemat podczas ładowania strony i nigdy nie zależy od magazynu lokalnego	fałsz
f-ShowPageHeader	Jeśli wartość true, zostanie wyświetlony nagłówek strony zawierający tytuł i ustawienia usługi Azure Data Explorer	true
f-HideConnectionPane	Jeśli wartość true, okienko połączenia po lewej stronie nie jest wyświetlane	fałsz
f-SkipMonacoFocusOnInit	Rozwiązuje problem z fokusem podczas hostowania elementu iframe	fałsz
f-Homepage	Włącz stronę główną i przekierowując nowych użytkowników do niej	true
f-ShowNavigation	Jeśli wartość true, zostanie wyświetlone okienko nawigacji po lewej stronie	true
f-DisableDashboardTopBar	Jeśli to prawda, ukrywa górny pasek na pulpicie nawigacyjnym	fałsz
f-DisableNewDashboard	Jeśli to prawda, ukrywa opcję dodawania nowego pulpitu nawigacyjnego	fałsz
f-DisableNewDashboard	Jeśli wartość true, ukrywa opcję wyszukiwania na liście pulpitów nawigacyjnych	fałsz
f-DisableDashboardEditMenu	Jeśli to prawda, ukrywa opcję edytowania pulpitu nawigacyjnego	fałsz
f-DisableDashboardFileMenu	Jeśli to prawda, ukrywa przycisk menu pliku na pulpicie nawigacyjnym	fałsz
f-DisableDashboardShareMenu	Jeśli to prawda, ukrywa przycisk menu udostępniania na pulpicie nawigacyjnym	fałsz
f-DisableDashboardDelete	Jeśli to prawda, ukrywa przycisk usuwania pulpitu nawigacyjnego	fałsz
f-DisableTileRefresh	Jeśli wartość true, wyłącza przycisk odświeżania kafelków na pulpicie nawigacyjnym	fałsz
f-DisableDashboardAutoRefresh	Jeśli wartość true, wyłącza automatyczne odświeżanie kafelków na pulpicie nawigacyjnym	fałsz
f-DisableExploreQuery	Jeśli wartość true, wyłącza przycisk eksploruj zapytanie kafelków	fałsz
f-DisableCrossFiltering	Jeśli to prawda, wyłącza funkcję filtrowania krzyżowego na pulpitach nawigacyjnych	fałsz
f-HideDashboardParametersBar	Jeśli wartość true, ukrywa pasek parametrów na pulpicie nawigacyjnym	fałsz

Osadzanie internetowego interfejsu użytkownika usługi Azure Data Explorer w elemecie iframe

Jak osadzić internetowy interfejs użytkownika w elemecie iframe

Obsługa uwierzytelniania

Osadzanie pulpitów nawigacyjnych

Flagi funkcji

Opinia

Opinia

Dodatkowe zasoby

Osadzanie internetowego interfejsu użytkownika usługi Azure Data Explorer w elemecie iframe

Jak osadzić internetowy interfejs użytkownika w elemecie iframe

Obsługa uwierzytelniania

Osadzanie pulpitów nawigacyjnych

Flagi funkcji

Zawartość pokrewna

Opinia

Opinia

Dodatkowe zasoby