Umstieg von Power BI Embedded

Wenn Sie Power BI-Berichte mit powerbi-client eingebettet haben, wird Ihnen die Icon Map Embed API bewusst vertraut vorkommen: ein iframe, ein Handle, Methoden, die Promises zurückgeben, Ereignisse, die Sie abonnieren, Filter, die Sie von Ihrer Seite aus setzen, Lesezeichen, die Sie erfassen und anwenden. Diese Seite ordnet das eine dem anderen zu.

Dieselben zwei Einbettungsmodelle

Power BI	Icon Map
Einbetten für Ihre Kunden (App besitzt die Daten)	Eine veröffentlichte Karte: `embed(element, { publishId })`
Einbetten für Ihre Organisation (Benutzer besitzt die Daten)	`embedForOrganization(element, { mapItem })`
Einbettungstoken von Ihrem Server	Einbettungstoken von Ihrem Server, für Veröffentlichungen mit Token-Schutz (`getToken`)
Entra-Token für den angemeldeten Benutzer	Dasselbe (`getToken(scopes)`) oder Anmeldung im Frame

Bootstrapping

// Power BI
const report = powerbi.embed(element, { type: "report", id, embedUrl, accessToken, settings });
report.on("loaded", () => { /* now it is safe to call things */ });

// Icon Map
const map = embed(element, { publishId, getToken });
await map.ready;      // optional - commands sent early are held, not lost

Power BI	Icon Map
`powerbi.embed(el, config)`	`embed(el, options)`
`powerbi.get(el)`	`getEmbed(el)`
`powerbi.reset(el)`	`reset(el)`
`powerbi.bootstrap()`, dann `embed()`: den Download starten, bevor Sie ein Token haben	`embed(el, { deferRender: true })`, dann `map.render({ getToken })`
`report.setAccessToken(token)`	`map.setToken({ token })`
Behandlung von `tokenExpiration`	Ereignis `tokenExpiring`
`report.reload()` / `refresh()`	`map.reload()` / `map.refreshData()`
`report.fullscreen()`	`map.fullscreen()`
`report.print()`	`map.print()`
`report.iframe`	`map.iframe`

Ein Unterschied, den Sie kennen sollten: Sie müssen nicht auf ein loaded-Ereignis warten, bevor Sie die API aufrufen. Früh gesendete Befehle werden zurückgehalten, bis die Karte sie beantworten kann.

Filter

Power BI	Icon Map
`getFilters()` / `setFilters()` / `removeFilters()`	`getFilters()` / `setFilters()` / `clearFilters()`
`updateFilters(operation, filters)` mit `Add`, `Replace`, `ReplaceAll`, `RemoveAll`	`updateFilters({ operation, filters })` mit `add`, `replace`, `replaceAll`, `removeAll`
Einfacher Filter (`In`)	Ein Listenwert: `{ region: ["EMEA", "APAC"] }`
Erweiterter Filter (Bereich)	`{ revenue: { low: 1000, high: 5000 } }`
Filter für relative Datumsangaben	`{ period: { operator: "inLast", count: 30, unit: "days" } }`
`filter.displaySettings` (`isLockedInViewMode`, `isHiddenInViewMode`, `displayName`)	`display: { region: { locked, hidden, displayName } }`
Jede Tabelle und Spalte im Modell	Nur vom Autor deklarierte Filter, ermittelbar mit `getFilterSchema()`

Die letzte Zeile ist der eigentliche Unterschied. In Power BI benennt Ihre Seite eine beliebige Spalte; in Icon Map benennt sie einen Filter, den der Autor anbieten wollte, und alles andere wird mit undeclared_filter abgelehnt. Siehe Filter.

Datenschnitte, Auswahl und Lesezeichen

Power BI	Icon Map
`visual.getSlicerState()` / `setSlicerState()`	`getSlicers()` / `setSlicerState({ slicerId, state })`
Ereignis `dataSelected`	`featureClick` und `selectionChanged`
Auswahl von Datenpunkten von Ihrer Seite aus	`selectByKey({ layerId, field, keys })`, `setSelection()`
-	`highlight()`: Hervorhebung ohne Auswahl, für das Überfahren von Listeneinträgen
`bookmarksManager.getBookmarks()` / `apply(name)`	`getBookmarks()` / `applyBookmark({ bookmarkId })`
`bookmarksManager.capture()` / `applyState(state)`	`captureScene()` / `applyScene({ scene })`
Ereignis `bookmarkApplied`	Ereignis `bookmarkApplied`
Berichts-URL mit `?bookmarkGuid=` oder `?filter=`	Deep Links: `?bookmark=`, `?f.<name>=`, `#s=`

Eine erfasste Szene ist ein einfaches, dokumentiertes Objekt statt einer undurchsichtigen Zeichenfolge, und sie übersteht eine erneute Veröffentlichung: Teile, die nicht mehr existieren, werden übersprungen und gemeldet, statt einen Fehler auszulösen.

Power BI	Icon Map
`settings.panes`, `filterPaneEnabled`, `navContentPaneEnabled`	`setChrome({ legend, layerControl, bookmarksBar, search ... })`
`settings.background: Transparent`	`setBackground({ background: "transparent" })`
`report.applyTheme()`	`setTheme({ mode })`: hell, dunkel oder automatisch. Benutzerdefinierte Designs werden nicht unterstützt
`settings.localeSettings`	Option `language`, `setLanguage()`
`settings.hyperlinkClickBehavior: RaiseEvent` + `dataHyperlinkClicked`	`hyperlinkBehavior: "raiseEvent"` + `linkClicked`
`getPages()` / `setPage()`	Keine Seiten. Am ehesten entsprechen dem Lesezeichen und `getLayers()` / `setVisibility()`
`setZoom` für Seite und Visual	Die Kameragruppe: `setView`, `flyTo`, `fitBounds`, `fitLayer`
`visual.exportData()`	Keine Entsprechung, mit Absicht (siehe unten)
`report.saveAs()`, Bearbeitungsmodus, `switchMode()`	Keine Entsprechung. Eine eingebettete Karte ist schreibgeschützt

Benutzerdefinierte Befehle

Power BI	Icon Map
Befehl über `settings.extensions` im Kontextmenü eines Visuals	`addMenuCommand({ id, title, layerIds? })` im Feature-Popup
Ereignis `commandTriggered`	Ereignis `menuCommandTriggered`

Ereignisse

Power BI	Icon Map
`loaded`	Promise `ready`, Ereignis `loaded`
`rendered`	`rendered` (mit `durationMs`)
`error`	Option `onError`, Ereignis `error`, abgelehnte Promises mit einem `code`
`pageChanged`	`bookmarkApplied`, `visibilityChanged`
`filtersApplied`	`filtersChanged`
`visualClicked`, `dataSelected`	`featureClick`, `selectionChanged`
-	`viewChanged`: die Kamera

Jedes Zustandsereignis von Icon Map enthält einen reason (user, command, bookmark ...), was bei Power BI nicht der Fall ist. So kann eine Seite, die die Karte spiegelt, das Echo ihrer eigenen Befehle ignorieren, siehe Ereignisse.

Was anders funktioniert

Funktionserkennung. Statt SDK- oder Dienstversionen zu prüfen, lesen Sie (await map.ready).commands. Die Liste enthält, was genau diese Karte beantwortet, unter Berücksichtigung der Kartenversion, der Art der Einbettung und der Schalter des Autors.
Der Autor hat die Kontrolle. Jede Befehlsgruppe kann pro Veröffentlichung deaktiviert werden, und nur Websites, die der Autor aufgeführt hat, können die Karte überhaupt steuern. Planen Sie denied_capability und denied_origin ein.
Keine Massendaten. Es gibt kein exportData(). featureClick liefert die Felder, die die Ebene in ihrer QuickInfo zeigt, und nichts liefert Zeilen in großer Menge. Wenn Ihre Seite die Daten benötigt, lesen Sie sie aus Ihrer eigenen Quelle und verknüpfen beides mit selectByKey.
Typisierte Fehler. Fehler sind EmbedErrors mit einem stabilen code statt Fehlerobjekten, deren message Sie auswerten müssen.
Größe. Das SDK ist etwa 17 KB groß, hat keine Abhängigkeiten und bietet einen Build für Script-Tags für Seiten, die nicht bündeln können.