Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
W tym przewodniku Szybki start użyjesz funkcji Fabric Embed, aby dodać pulpit nawigacyjny Microsoft Fabric Real-Time do aplikacji internetowej JavaScript lub TypeScript opartej na przeglądarce. Korzystając z Fabric Embed, aplikacja może wyświetlać pulpit nawigacyjny użytkownikom, którzy uzyskują do niego dostęp przy użyciu tożsamości Microsoft Entra ID i delegowanych uprawnień.
Aplikacja używa biblioteki Microsoft Authentication Library for JavaScript (MSAL.js) do uzyskania delegowanego tokenu dostępu dla zasobu API Microsoft Fabric oraz zestawu Fabric Embed SDK do wyświetlania pulpitu nawigacyjnego. Po zakończeniu aplikacja wyświetla pulpit nawigacyjny Real-Time bez wysyłania użytkowników do portalu Fabric.
Wymagania wstępne dotyczące osadzania pulpitu nawigacyjnego Real-Time
Przed rozpoczęciem skonfiguruj środowisko dla osadzania w usłudze Microsoft Fabric. Ta konfiguracja tworzy lub potwierdza rejestrację aplikacji Microsoft Entra, uprawnienia delegowane, obszar roboczy Microsoft Fabric, aktywną pojemność usługi Fabric oraz wartości na pulpicie nawigacyjnym wykorzystywane w tym przewodniku Szybki start.
Potrzebne są również następujące wartości i uprawnienia.
| Wymaganie | Description |
|---|---|
| Projekt aplikacji internetowej | Aplikacja JavaScript lub TypeScript oparta na przeglądarce, która używa narzędzia npm. Kod osadzania w tym przewodniku Szybki start działa po stronie klienta. |
| Microsoft Entra identyfikator klienta rejestracji aplikacji | Identyfikator klienta rejestracji aplikacji służącej do logowania użytkowników przy użyciu biblioteki MSAL.js. |
| Identyfikator dzierżawy Microsoft Entra | Identyfikator dzierżawy, w której skonfigurowano rejestrację aplikacji oraz użytkowników usługi Fabric. |
| Delegowane uprawnienia interfejsu API | Zgoda delegowana dla Fabric.Embed i Item.Read.All. Żądanie tokenu MSAL używa zakresu Fabric .default, aby zażądać tych uprawnień objętych zgodą. |
| Identyfikator obszaru roboczego | Identyfikator obszaru roboczego Microsoft Fabric, który zawiera pulpit nawigacyjny w czasie rzeczywistym i jest przypisany do aktywnej pojemności usługi Fabric. |
| identyfikator elementu pulpitu nawigacyjnego czasu rzeczywistego | Identyfikator elementu Microsoft Fabric dla pulpitu nawigacyjnego Real-Time, który chcesz osadzić. |
| Dostęp użytkowników | Zalogowany użytkownik może otworzyć pulpit nawigacyjny Real-Time w Fabric. Osadzony pulpit nawigacyjny używa delegowanych uprawnień tego użytkownika. |
Uwaga / Notatka
Microsoft Fabric Embed jest dostępny w publicznej wersji zapoznawczej. Aby uzyskać informacje o obsługiwanych typach elementów i ograniczeniach uwierzytelniania, zobacz Ograniczenia dotyczące Microsoft Fabric Embed.
Instalacja MSAL.js i SDK do osadzania Fabric
W folderze projektu aplikacji webowej zainstaluj pakiety klienta używane w tym przewodniku szybkiego startu.
npm install @azure/msal-browser @microsoft/fabric-embed
Jeśli instrukcje wdrożenia dla wersji zapoznawczej zawierają zależne od wersji polecenie dotyczące pakietu SDK Fabric Embed, użyj tego polecenia dla pakietu @microsoft/fabric-embed. Po instalacji upewnij się, że package.json wyświetla @azure/msal-browser i @microsoft/fabric-embed w dependencies.
Konfigurowanie uwierzytelniania Microsoft Entra na potrzeby osadzania Microsoft Fabric
MSAL.js (@azure/msal-browser) umożliwia użytkownikowi zalogowanie się i uzyskuje delegowany token dostępu z platformy tożsamości firmy Microsoft dla aplikacji https://api.fabric.microsoft.com. Zakres .default pyta Microsoft Entra ID o delegowane uprawnienia Fabric, na które już wyraziłeś zgodę na rejestrację aplikacji, w tym Fabric.Embed i Item.Read.All.
Aby uzyskać więcej informacji, zobacz omówienie biblioteki Microsoft Authentication Library (MSAL).
Dodaj ten kod do pliku lub modułu uwierzytelniania po stronie klienta Twojej aplikacji przed wywołaniem kodu osadzania getAccessToken().
import {
AuthenticationResult,
InteractionRequiredAuthError,
PublicClientApplication,
} from "@azure/msal-browser";
const msal = new PublicClientApplication({
auth: {
clientId: "<client-id>",
authority: "https://login.microsoftonline.com/<tenant-id>",
redirectUri: window.location.origin,
},
});
const defaultScopes = ["https://api.fabric.microsoft.com/.default"];
async function getAccessToken(requestedScopes?: string[]): Promise<string> {
const scopes = requestedScopes ?? defaultScopes;
let accounts = msal.getAllAccounts();
if (accounts.length === 0) {
await msal.loginPopup({ scopes });
accounts = msal.getAllAccounts();
}
const account = accounts[0];
if (!account) {
throw new Error("No Microsoft Entra account is signed in.");
}
let result: AuthenticationResult;
try {
result = await msal.acquireTokenSilent({ scopes, account });
} catch (error) {
if (error instanceof InteractionRequiredAuthError) {
result = await msal.acquireTokenPopup({ scopes, account });
} else {
throw error;
}
}
return result.accessToken;
}
Zastąp elementy <client-id> i <tenant-id>, łącznie z nawiasami ostrymi, wartościami z rejestracji aplikacji w Microsoft Entra. Funkcja getAccessToken() zwraca delegowany token dostępu Microsoft Fabric dla zalogowanego użytkownika Microsoft Entra lub zgłasza błąd, jeśli żaden użytkownik nie zalogował się.
Dodawanie kontenera HTML dla osadzonego pulpitu nawigacyjnego Real-Time
Dodaj element HTML, w którym zestaw SDK osadzania Fabric renderuje pulpit nawigacyjny Microsoft Fabric Real-Time. Wartość id musi odpowiadać odwołaniu do kontenera w kodzie osadzenia. Elementy role i aria-label identyfikują osadzony obszar pulpitu nawigacyjnego dla użytkowników czytników ekranu.
<div
id="fabric-embed-container"
role="region"
aria-label="Embedded Fabric Real-Time Dashboard"
></div>
Konfigurowanie dostawcy tokenu dostępu na potrzeby odświeżania tokenu zestawu SDK osadzania Fabric
Skonfiguruj dostawcę tokenu dostępu używanego przez SDK osadzania Fabric do odświeżania delegowanych tokenów dostępu do usługi Microsoft Fabric dla osadzonego pulpitu nawigacyjnego w czasie rzeczywistym. Poniższy przykład implementuje accessTokenProvider przy użyciu getAccessToken() funkcji .
const accessTokenProvider = {
callback: async (input?: { scopes?: string[] }) => {
const token = await getAccessToken(input?.scopes);
return { token };
},
};
Osadzanie pulpitu nawigacyjnego Real-Time przy użyciu zestawu SDK osadzania Fabric
Użyj zestawu Fabric Embed SDK, aby wyświetlić pulpit na żywo usługi Microsoft Fabric w kontenerze HTML. Typy SDK w publicznej wersji zapoznawczej użyte w tym przykładzie korzystają z nazw KQLDashboard* na potrzeby osadzania pulpitu nawigacyjnego Real-Time Dashboard.
Konfiguracja osadzania używa tych wartości.
| Pole konfiguracji | Value |
|---|---|
itemId |
Identyfikator elementu pulpitu nawigacyjnego Real-Time z wymagań wstępnych. |
workspaceId |
Identyfikator obszaru roboczego Microsoft Fabric z sekcji Wymagania wstępne. |
accessToken |
Delegowany token dostępu do Microsoft Fabric zwrócony przez getAccessToken(). |
accessTokenProvider |
Funkcja zwrotna odświeżająca delegowane tokeny w osadzonym pulpicie nawigacyjnym. |
viewMode |
KQLDashboardViewMode.View, który odpowiada za renderowanie panelu do wyświetlenia. |
import {
EmbedManager,
KQLDashboardEmbedClient,
KQLDashboardViewMode,
KQLDashboardEmbedConfiguration,
} from "@microsoft/fabric-embed";
const embedManager = new EmbedManager({
embedClientClasses: [KQLDashboardEmbedClient],
});
async function embedDashboard() {
const container = document.getElementById("fabric-embed-container");
if (!container) {
throw new Error("The Fabric embed container was not found.");
}
const token = await getAccessToken();
const embedConfig: KQLDashboardEmbedConfiguration = {
accessToken: { token },
itemId: "<real-time-dashboard-item-id>",
itemType: "KQLDashboard",
workspaceId: "<workspace-id>",
viewMode: KQLDashboardViewMode.View,
eventHooks: { accessTokenProvider },
};
const client: KQLDashboardEmbedClient = embedManager.embed(container, embedConfig);
client.on("rendered", () => {
console.log("Real-Time Dashboard rendered.");
});
client.on("error", (error: unknown) => {
console.error("Microsoft Fabric Embed error:", error);
});
}
embedDashboard();
Zastąp <real-time-dashboard-item-id> i <workspace-id>, łącznie z nawiasami ostrymi, identyfikatorami elementu Fabric i obszaru roboczego.
Po uruchomieniu kodu pakiet SDK wyświetla panel Real-Time Dashboard w kontenerze i wypisuje Real-Time Dashboard rendered. w konsoli przeglądarki.
Ważna
Nazwy typów zestawu SDK w tym artykule używają terminologii publicznej w wersji zapoznawczej. Jeśli zainstalowany pakiet w wersji zapoznawczej używa różnych nazw typów, użyj nazw z tej wersji pakietu. Informacje o innych zastrzeżeniach dotyczących umowy wersji zapoznawczej można znaleźć w artykule Ograniczenia funkcji Microsoft Fabric Embed.
Weryfikowanie pulpitu nawigacyjnego osadzania Microsoft Fabric w czasie rzeczywistym
Zestaw SDK pomyślnie osadza pulpit nawigacyjny po wyświetleniu go w fabric-embed-container regionie i w dziennikach Real-Time Dashboard rendered.konsoli przeglądarki.
Jeśli panel nie wyświetla się, użyj szczegółów zdarzenia SDK error i sprawdź następujące elementy.
| Sprawdź | Co należy zweryfikować |
|---|---|
| Dostęp użytkowników | Zalogowany użytkownik usługi Microsoft Entra może otworzyć pulpit nawigacyjny czasu rzeczywistego w usłudze Fabric. |
| Wydajność | Obszar roboczy zawierający pulpit nawigacyjny Real-Time jest przypisany do aktywnej pojemności Fabric. |
| URI przekierowania | Rejestracja aplikacji w Microsoft Entra zawiera adres URI przekierowania dla Twojej aplikacji internetowej. |
| Uprawnienia delegowane | Rejestracja aplikacji ma udzieloną zgodę delegowaną dla Fabric.Embed i Item.Read.All (lub KQLDashboard.Read.All), a żądanie tokenu używa zakresu Fabric .default. |
| Identifiers | Identyfikator obszaru roboczego i identyfikator elementu pulpitu nawigacyjnego Real-Time Dashboard odpowiadają zawartości w usłudze Fabric, którą chcesz osadzić. |
| Kontener HTML | Element fabric-embed-container istnieje, ma dostępną nazwę i pozostaje osiągalny za pomocą klawiatury w układzie aplikacji. |
| Obsługa błędów zestawu SDK | Aplikacja obsługuje zdarzenie pakietu Fabric Embed SDK error i rejestruje szczegóły błędu. |