Si vous venez de Power BI Embedded

Si vous avez incorporé des rapports Power BI avec powerbi-client, l'API Embed d'Icon Map vous semblera familière, et c'est voulu : un iframe, un handle, des méthodes qui renvoient des promesses, des événements auxquels vous vous abonnez, des filtres que vous définissez depuis votre page, des signets que vous capturez et appliquez. Cette page établit la correspondance entre les deux.

Les deux mêmes modèles d'incorporation

Power BI	Icon Map
Incorporer pour vos clients (l'application détient les données)	Une carte publiée : `embed(element, { publishId })`
Incorporer pour votre organisation (l'utilisateur détient les données)	`embedForOrganization(element, { mapItem })`
Jeton d'incorporation fourni par votre serveur	Jeton d'intégration fourni par votre serveur, pour les publications protégées par jeton (`getToken`)
Jeton Entra pour l'utilisateur connecté	La même chose (`getToken(scopes)`), ou connexion à l'intérieur du cadre

Initialisation

// 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()` puis `embed()` : lancer le téléchargement avant d'avoir un jeton	`embed(el, { deferRender: true })` puis `map.render({ getToken })`
`report.setAccessToken(token)`	`map.setToken({ token })`
Gestion de `tokenExpiration`	Événement `tokenExpiring`
`report.reload()` / `refresh()`	`map.reload()` / `map.refreshData()`
`report.fullscreen()`	`map.fullscreen()`
`report.print()`	`map.print()`
`report.iframe`	`map.iframe`

Une différence à connaître : vous n'avez pas besoin d'attendre un événement loaded avant d'appeler l'API. Les commandes émises tôt sont mises en attente jusqu'à ce que la carte puisse y répondre.

Filtres

Power BI	Icon Map
`getFilters()` / `setFilters()` / `removeFilters()`	`getFilters()` / `setFilters()` / `clearFilters()`
`updateFilters(operation, filters)` avec `Add`, `Replace`, `ReplaceAll`, `RemoveAll`	`updateFilters({ operation, filters })` avec `add`, `replace`, `replaceAll`, `removeAll`
Filtre de base (`In`)	Une valeur de liste : `{ region: ["EMEA", "APAC"] }`
Filtre avancé (plage)	`{ revenue: { low: 1000, high: 5000 } }`
Filtre de date relative	`{ period: { operator: "inLast", count: 30, unit: "days" } }`
`filter.displaySettings` (`isLockedInViewMode`, `isHiddenInViewMode`, `displayName`)	`display: { region: { locked, hidden, displayName } }`
N'importe quelle table et colonne du modèle	Uniquement les filtres déclarés par l'auteur, à découvrir avec `getFilterSchema()`

La dernière ligne est la vraie différence. Dans Power BI, votre page nomme n'importe quelle colonne ; dans Icon Map, elle nomme un filtre que l'auteur a choisi de proposer, et tout le reste est rejeté avec undeclared_filter. Voir Filtres.

Segments, sélection et signets

Power BI	Icon Map
`visual.getSlicerState()` / `setSlicerState()`	`getSlicers()` / `setSlicerState({ slicerId, state })`
Événement `dataSelected`	`featureClick` et `selectionChanged`
Sélection de points de données depuis votre page	`selectByKey({ layerId, field, keys })`, `setSelection()`
-	`highlight()` : mise en évidence sans sélection, pour le survol d'une liste
`bookmarksManager.getBookmarks()` / `apply(name)`	`getBookmarks()` / `applyBookmark({ bookmarkId })`
`bookmarksManager.capture()` / `applyState(state)`	`captureScene()` / `applyScene({ scene })`
Événement `bookmarkApplied`	Événement `bookmarkApplied`
URL de rapport avec `?bookmarkGuid=` ou `?filter=`	Liens profonds : `?bookmark=`, `?f.<name>=`, `#s=`

Une scène capturée est un objet simple et documenté plutôt qu'une chaîne opaque, et elle survit à une republication : les parties qui n'existent plus sont ignorées et signalées au lieu de provoquer un échec.

Power BI	Icon Map
`settings.panes`, `filterPaneEnabled`, `navContentPaneEnabled`	`setChrome({ legend, layerControl, bookmarksBar, search ... })`
`settings.background: Transparent`	`setBackground({ background: "transparent" })`
`report.applyTheme()`	`setTheme({ mode })` : clair, sombre ou automatique. Les thèmes personnalisés ne sont pas pris en charge
`settings.localeSettings`	Option `language`, `setLanguage()`
`settings.hyperlinkClickBehavior: RaiseEvent` + `dataHyperlinkClicked`	`hyperlinkBehavior: "raiseEvent"` + `linkClicked`
`getPages()` / `setPage()`	Pas de pages. Les équivalents les plus proches sont les signets et `getLayers()` / `setVisibility()`
`setZoom` de page et de visuel	Le groupe caméra : `setView`, `flyTo`, `fitBounds`, `fitLayer`
`visual.exportData()`	Aucun équivalent, à dessein : voir ci-dessous
`report.saveAs()`, mode édition, `switchMode()`	Aucun équivalent. Une carte incorporée est en lecture seule

Commandes personnalisées

Power BI	Icon Map
Commande `settings.extensions` dans le menu contextuel d'un visuel	`addMenuCommand({ id, title, layerIds? })` dans la fenêtre contextuelle d'entité
Événement `commandTriggered`	Événement `menuCommandTriggered`

Événements

Power BI	Icon Map
`loaded`	Promesse `ready`, événement `loaded`
`rendered`	`rendered` (avec `durationMs`)
`error`	Option `onError`, événement `error`, promesses rejetées avec un `code`
`pageChanged`	`bookmarkApplied`, `visibilityChanged`
`filtersApplied`	`filtersChanged`
`visualClicked`, `dataSelected`	`featureClick`, `selectionChanged`
-	`viewChanged` : la caméra

Chaque événement d'état d'Icon Map porte une reason (user, command, bookmark ...), ce que ne font pas ceux de Power BI. Elle existe pour qu'une page qui reflète la carte puisse ignorer l'écho de ses propres commandes : voir Événements.

Ce qui fonctionne différemment

Détection des fonctionnalités. Au lieu de vérifier les versions du SDK ou du service, lisez (await map.ready).commands. Cette liste indique ce à quoi répond cette carte précise, en tenant compte de la version de la carte, du type d'incorporation et des réglages de l'auteur.
L'auteur garde le contrôle. Chaque groupe de commandes peut être désactivé pour chaque publication, et seuls les sites listés par l'auteur peuvent piloter la carte. Prévoyez denied_capability et denied_origin.
Pas de données en masse. Il n'existe pas de exportData(). featureClick renvoie les champs que la couche affiche dans son info-bulle, et rien ne renvoie de lignes en masse. Si votre page a besoin des données, lisez-les depuis votre propre source et utilisez selectByKey pour relier les deux.
Erreurs typées. Les échecs sont des EmbedError avec un code stable, plutôt que des objets d'erreur dont vous devez analyser le message.
Taille. Le SDK pèse environ 17 KB sans aucune dépendance, et il existe une version pour balise script destinée aux pages qui ne peuvent pas utiliser de bundler.