Vindo do Power BI Embedded

Se você já incorporou relatórios do Power BI com powerbi-client, a API de incorporação do Icon Map vai parecer familiar de propósito: um iframe, um handle, métodos que retornam promises, eventos aos quais você se inscreve, filtros que você define a partir da sua página, indicadores que você captura e aplica. Esta página faz a correspondência entre um e outro.

Os mesmos dois modelos de incorporação

Power BI	Icon Map
Inserir para seus clientes (o aplicativo possui os dados)	Um mapa publicado: `embed(element, { publishId })`
Inserir para sua organização (o usuário possui os dados)	`embedForOrganization(element, { mapItem })`
Token de inserção gerado pelo seu servidor	Token de incorporação gerado pelo seu servidor, para publicações protegidas por token (`getToken`)
Token do Entra para o usuário conectado	O mesmo (`getToken(scopes)`), ou entrada dentro do frame

Inicialização

// 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()` e depois `embed()`: inicia o download antes de você ter um token	`embed(el, { deferRender: true })` e depois `map.render({ getToken })`
`report.setAccessToken(token)`	`map.setToken({ token })`
Tratamento de `tokenExpiration`	Evento `tokenExpiring`
`report.reload()` / `refresh()`	`map.reload()` / `map.refreshData()`
`report.fullscreen()`	`map.fullscreen()`
`report.print()`	`map.print()`
`report.iframe`	`map.iframe`

Uma diferença que vale a pena conhecer: você não precisa esperar um evento loaded antes de chamar a API. Os comandos emitidos cedo ficam retidos até que o mapa possa respondê-los.

Filtros

Power BI	Icon Map
`getFilters()` / `setFilters()` / `removeFilters()`	`getFilters()` / `setFilters()` / `clearFilters()`
`updateFilters(operation, filters)` com `Add`, `Replace`, `ReplaceAll`, `RemoveAll`	`updateFilters({ operation, filters })` com `add`, `replace`, `replaceAll`, `removeAll`
Filtro básico (`In`)	Um valor de lista: `{ region: ["EMEA", "APAC"] }`
Filtro avançado (intervalo)	`{ revenue: { low: 1000, high: 5000 } }`
Filtro de data relativa	`{ period: { operator: "inLast", count: 30, unit: "days" } }`
`filter.displaySettings` (`isLockedInViewMode`, `isHiddenInViewMode`, `displayName`)	`display: { region: { locked, hidden, displayName } }`
Qualquer tabela e coluna do modelo	Somente os filtros que o autor declarou: descubra-os com `getFilterSchema()`

A última linha é a diferença real. No Power BI, sua página indica qualquer coluna; no Icon Map, ela indica um filtro que o autor escolheu oferecer, e qualquer outro é rejeitado com undeclared_filter. Veja Filtros.

Segmentações, seleção e indicadores

Power BI	Icon Map
`visual.getSlicerState()` / `setSlicerState()`	`getSlicers()` / `setSlicerState({ slicerId, state })`
Evento `dataSelected`	`featureClick` e `selectionChanged`
Seleção de ponto de dados a partir da sua página	`selectByKey({ layerId, field, keys })`, `setSelection()`
-	`highlight()`: destaque sem seleção, para o hover em listas
`bookmarksManager.getBookmarks()` / `apply(name)`	`getBookmarks()` / `applyBookmark({ bookmarkId })`
`bookmarksManager.capture()` / `applyState(state)`	`captureScene()` / `applyScene({ scene })`
Evento `bookmarkApplied`	Evento `bookmarkApplied`
URL do relatório com `?bookmarkGuid=` ou `?filter=`	Links diretos: `?bookmark=`, `?f.<name>=`, `#s=`

Uma cena capturada é um objeto simples e documentado, e não uma string opaca, e sobrevive a uma nova publicação: as partes que não existem mais são ignoradas e informadas, em vez de causar uma falha.

Apresentação e navegação

Power BI	Icon Map
`settings.panes`, `filterPaneEnabled`, `navContentPaneEnabled`	`setChrome({ legend, layerControl, bookmarksBar, search ... })`
`settings.background: Transparent`	`setBackground({ background: "transparent" })`
`report.applyTheme()`	`setTheme({ mode })`: claro, escuro ou automático. Temas personalizados não são suportados
`settings.localeSettings`	Opção `language`, `setLanguage()`
`settings.hyperlinkClickBehavior: RaiseEvent` + `dataHyperlinkClicked`	`hyperlinkBehavior: "raiseEvent"` + `linkClicked`
`getPages()` / `setPage()`	Não há páginas. O mais próximo são os indicadores e `getLayers()` / `setVisibility()`
`setZoom` de página e de visual	O grupo da câmera: `setView`, `flyTo`, `fitBounds`, `fitLayer`
`visual.exportData()`	Não há equivalente, por design (veja abaixo)
`report.saveAs()`, modo de edição, `switchMode()`	Não há equivalente. Um mapa incorporado é somente leitura

Comandos personalizados

Power BI	Icon Map
Comando `settings.extensions` no menu de contexto de um visual	`addMenuCommand({ id, title, layerIds? })` no pop-up da feição
Evento `commandTriggered`	Evento `menuCommandTriggered`

Eventos

Power BI	Icon Map
`loaded`	Promise `ready`, evento `loaded`
`rendered`	`rendered` (com `durationMs`)
`error`	Opção `onError`, evento `error`, promises rejeitadas com um `code`
`pageChanged`	`bookmarkApplied`, `visibilityChanged`
`filtersApplied`	`filtersChanged`
`visualClicked`, `dataSelected`	`featureClick`, `selectionChanged`
-	`viewChanged`: a câmera

Todo evento de estado do Icon Map traz um reason (user, command, bookmark ...), o que os do Power BI não trazem. Ele existe para que uma página que espelha o mapa possa ignorar o eco dos próprios comandos. Veja Eventos.

O que funciona de forma diferente

Detecção de recursos. Em vez de verificar versões do SDK ou do serviço, leia (await map.ready).commands. A lista mostra o que este mapa específico responde, considerando a versão do mapa, o tipo de incorporação e as chaves do autor.
O autor está no controle. Cada grupo de comandos pode ser desativado por publicação, e só os sites que o autor listou podem controlar o mapa. Prepare-se para denied_capability e denied_origin.
Sem dados em massa. Não existe exportData(). featureClick retorna os campos que a camada mostra na dica de ferramenta, e nada retorna linhas em massa. Se a sua página precisar dos dados, leia-os da sua própria fonte e use selectByKey para ligar os dois.
Erros tipados. As falhas são EmbedErrors com um code estável, e não objetos de erro cuja message você precisa interpretar.
Tamanho. O SDK tem cerca de 17 KB, sem dependências, e há uma versão para tag de script para páginas que não usam bundler.