Idioma

Português

Referência da Embed API

Todos os comandos e eventos da API de incorporação do Icon Map, gerados a partir do contrato TypeScript do SDK. Cada comando é um método do handle que embed() retorna e é resolvido com o resultado indicado, ou rejeitado com um EmbedError cujo code é um dos códigos de erro.

Um comando marcado como read também exige a chave Read state and events do autor. Os tipos citados aqui (EmbedCamera, EmbedScene ...) são exportados por @iconmap/embed.

Comandos

Sessão

Sempre disponíveis depois que uma sessão é aberta. Não estão sujeitos à política do autor.

Comando	Argumentos	Resolvido com	Observações
`ping`	-	`{ protocol: number; uptimeMs: number }`	Ida e volta até o visualizador. Útil como verificação de atividade e para deixar uma mensagem assíncrona anterior se concluir.
`getCapabilities`	-	`EmbedCapabilities`	O descritor de capacidades novamente (o mesmo objeto com que `ready` foi resolvido).
`setToken`	`{ token: string }`	-	Envia um token de incorporação novo antes que o antigo expire (veja `tokenExpiring`). Somente mapas publicados.
`setLanguage`	`{ language: string }`	-	Muda o idioma do leitor. Somente um idioma de `capabilities.map.locales`; qualquer outro é rejeitado com `invalid_args`, nunca há um fallback silencioso.

Câmera

Move e lê a vista. Grupo de política: camera.

Comando	Argumentos	Resolvido com	Observações
`getView`	-	`EmbedViewState`	read A câmera e os limites visíveis.
`setView`	`Partial<EmbedCamera> & { animate?: boolean }`	-	Define qualquer um entre center / zoom / bearing / pitch. Salta, a menos que `animate` seja true.
`flyTo`	`Partial<EmbedCamera> & { durationMs?: number; curve?: number }`	-	Um voo animado até uma câmera.
`fitBounds`	`{ bounds: EmbedBounds; padding?: EmbedPadding; maxZoom?: number; animate?: boolean; pitch?: number; bearing?: number }`	-	Enquadra uma caixa delimitadora. `pitch` / `bearing` são onde a câmera para; se omitidos, ela mantém a inclinação atual (passe `pitch: 0, bearing: 0` para um enquadramento plano, com o norte para cima, depois de um voo inclinado).
`fitLayer`	`{ layerId: string; padding?: EmbedPadding; maxZoom?: number; pitch?: number; bearing?: number }`	-	Enquadra os dados de uma camada conforme filtrados no momento. `unknown_id` quando a camada não tem extensão. `pitch` / `bearing` como em `fitBounds`.
`zoomBy`	`{ delta: number; animate?: boolean }`	-	Aproxima ou afasta por um delta, limitado ao intervalo do mapa.
`resize`	-	-	Avisa o mapa de que o contêiner mudou de tamanho (depois que você redimensiona o pai do frame).
`setMaxBounds`	`{ bounds: EmbedBounds \| null }`	-	Restringe o deslocamento a uma caixa; `null` remove o limite.

Camadas e visibilidade

Mostra e oculta o que o autor publicou. Somente visibilidade, nunca estilo. Grupo de política: layers.

Comando	Argumentos	Resolvido com	Observações
`getLayers`	-	`EmbedLayerInfo[]`	read As camadas do mapa: id, nome, tipo e se cada uma está sendo exibida agora.
`getVisibility`	-	`EmbedVisibility`	read Todas as alternâncias da cena, completamente preenchidas: camadas, rótulos e grupos de feições do mapa base, terminador, sombreamento, visuais.
`setVisibility`	`EmbedVisibility`	`{ skipped: string[] } \| void`	Aplica um instantâneo parcial de visibilidade: o que você não incluir fica como está. IDs desconhecidos são ignorados e informados. Ocultar uma segmentação a DESATIVA, como em um indicador: sua seleção deixa de filtrar até que ela volte a ser exibida. Para filtrar o mapa sem mostrar um cartão, use o grupo de filtros (`setFilters`).
`setLayerVisibility`	`{ layerId: string; visible: boolean }`	-	Mostra ou oculta uma camada.
`resetVisibility`	-	-	Volta todas as alternâncias ao estado publicado pelo autor.
`getVisuals`	-	`EmbedVisualInfo[]`	read Os gráficos, segmentações, caixas de texto e outros visuais do mapa, com a visibilidade de cada um.
`getLayerStats`	`{ layerId: string }`	`{ layerId: string; visibleFeatureCount: number }`	read Quantas feições a camada contém agora, depois dos filtros e das segmentações.

Filtros declarados

Valores para os filtros que o autor declarou no mapa. Somente mapas publicados. Grupo de política: filters.

Comando	Argumentos	Resolvido com	Observações
`getFilterSchema`	-	`EmbedFilterSchemaEntry[]`	read Os filtros que o autor declarou: nome, tipo, operadores, padrão. Construa sua própria interface de filtros a partir disso.
`getFilters`	-	`EmbedFilterValues`	read Os valores de filtro aplicados no momento.
`setFilters`	`EmbedFilterValues`	-	Substitui os valores de filtro. Um nome que o autor não declarou é rejeitado com `undeclared_filter` antes que qualquer coisa seja aplicada.
`updateFilters`	`{ operation: EmbedFilterOperation; filters?: EmbedFilterValues; display?: Record<string, EmbedFilterDisplay> }`	-	Adiciona, substitui ou remove filtros individuais, no estilo do Power BI, com configurações de exibição opcionais por filtro (`locked`, `hidden`, `displayName`).
`clearFilters`	-	-	Remove todos os valores de filtro da página host.

Dados

Executa novamente as consultas ao vivo. Somente mapas publicados. Grupo de política: data.

Comando	Argumentos	Resolvido com	Observações
`refreshData`	`{ bindingIds?: string[] } \| void`	`{ refreshed: string[] }`	Executa novamente as consultas ao vivo, ignorando o cache de resultados. É resolvido com os IDs de vinculação atualizados (vazio em um mapa de instantâneo).

Segmentações de dados

Controla as segmentações do leitor. Grupo de política: slicers.

Comando	Argumentos	Resolvido com	Observações
`getSlicers`	-	`EmbedSlicerInfo[]`	read As segmentações do mapa e o estado atual de cada uma.
`getSlicerValues`	`{ slicerId: string; search?: string }`	`{ values: unknown[]; truncated: boolean }`	read Os valores que uma segmentação de lista oferece, opcionalmente restritos por uma string de pesquisa. Também funciona para uma segmentação oculta.
`setSlicerState`	`{ slicerId: string; state: EmbedSlicerState }`	-	Define a seleção de uma segmentação, exatamente como se o leitor a tivesse feito.
`clearSlicer`	`{ slicerId: string }`	-	Limpa uma segmentação.
`clearAllSlicers`	-	-	Limpa todas as segmentações.

Seleção e realce

Seleciona feições, aplica filtro cruzado a gráficos, realça sem selecionar. Grupo de política: selection.

Comando	Argumentos	Resolvido com	Observações
`getSelection`	-	`EmbedSelection`	read As chaves das feições selecionadas, por ID de camada.
`setSelection`	`EmbedSelection`	`{ skipped: string[] } \| void`	Substitui a seleção. IDs de camada desconhecidos são ignorados e informados.
`clearSelection`	-	-	Limpa a seleção.
`selectByKey`	`{ layerId: string; keys: Array<string \| number>; field?: string; zoomTo?: boolean }`	`{ matched: number }`	Seleciona feições pelas suas próprias chaves: com `field`, as chaves são comparadas com os valores desse campo ("ativo 41B"); sem ele, são chaves de feição como `featureClick` as informou. `zoomTo` enquadra o resultado. No máximo 500 chaves. `field` precisa ser uma coluna que o mapa publicado contém. Um mapa publicado tem apenas as colunas que usa (dicas de ferramenta, estilo, rótulos, segmentações), então uma coluna de chave que nada mais usa não está lá e não encontra nada: o autor a adiciona aos campos da dica de ferramenta da camada.
`getChartSelection`	-	`Record<string, EmbedChartDatum[]>`	read Os pontos de dados selecionados em cada gráfico (o filtro cruzado do mapa), por ID de gráfico.
`setChartSelection`	`{ chartId: string; datums: EmbedChartDatum[] }`	-	Seleciona pontos de dados em um gráfico, o que aplica filtro cruzado ao mapa como um clique faria.
`clearChartSelection`	`{ chartId?: string } \| void`	-	Limpa a seleção de um gráfico, ou de todos.
`closePopups`	-	-	Fecha o pop-up da feição, se houver um aberto.
`highlight`	`{ layerId: string; keys: Array<string \| number>; field?: string }`	`{ matched: number }`	Destaque temporário: pinta `keys` em `layerId` como selecionadas SEM alterar a seleção: sem pop-up, sem escopo de painel, sem `selectionChanged`. O próximo clique do leitor o substitui. Com `field`, as chaves são resolvidas por esse campo, como em `selectByKey`.
`clearHighlight`	-	-	Remove um realce definido com `highlight`.

Cenas, indicadores e tours

Captura e restaura o estado completo da sessão. Grupo de política: scenes.

Comando	Argumentos	Resolvido com	Observações
`captureScene`	`{ include?: Array<keyof EmbedScene>; opaque?: boolean } \| void`	`EmbedScene \| { state: string }`	read O estado completo da sessão como um único objeto serializável: câmera, visibilidade, segmentações, filtros, seleção, mapa base. Guarde-o ou transforme-o em um link com `sceneToUrl`.
`applyScene`	`{ scene: EmbedScene \| { state: string }; animate?: boolean }`	`{ skipped: string[] }`	Restaura uma cena capturada. IDs que o mapa não tem mais são ignorados e informados, então uma cena sobrevive a uma nova publicação.
`resetScene`	-	-	Volta tudo ao estado publicado pelo autor.
`getBookmarks`	-	`EmbedBookmarkInfo[]`	read Os indicadores do autor. Vazio, a menos que o autor tenha escolhido oferecer indicadores ao publicar o mapa.
`applyBookmark`	`{ bookmarkId: string; animate?: boolean }`	-	Aplica um indicador pelo mesmo caminho que a barra de indicadores usa.
`getTours`	-	`EmbedTourInfo[]`	read Os tours do autor.
`playTour`	`{ tourId: string }`	-	Inicia um tour. Os eventos de câmera gerados durante a reprodução trazem `reason: "tour"`.
`stopTour`	-	-	Para o tour em reprodução.

Apresentação

Mapa base, controles, tema, legenda, exportação de imagem. Grupo de política: presentation.

Comando	Argumentos	Resolvido com	Observações
`getBasemaps`	-	`EmbedBasemapInfo[]`	read Os mapas base que o autor publicou para este mapa, e qual está ativo.
`setBasemap`	`{ basemapId: string }`	-	Muda para um dos mapas base publicados. Não há como carregar um estilo próprio.
`setChrome`	`EmbedChromeSettings`	-	Oculta ou mostra os controles do próprio mapa (legenda, controle de camadas, pop-ups, barra de indicadores, controles do tour, pesquisa). Uma chave pode ocultar um controle que o autor configurou; não pode adicionar um que ele não configurou.
`setTheme`	`EmbedThemeSettings`	-	Claro, escuro ou seguir o mapa.
`setBackground`	`{ background: "default" \| "transparent" }`	-	Torna transparente a página por trás do mapa, para que o seu próprio fundo apareça.
`getLegend`	-	`EmbedLegendEntry[]`	read A legenda como está renderizada no momento, em forma de dados: crie sua própria legenda fora do frame.
`getMapInfo`	-	`EmbedMapInfo`	read O descritor do mapa: título, descrição, modo de dados, idiomas e a atribuição que você precisa exibir se ocultar nossos controles.
`print`	-	-	Abre a caixa de diálogo de impressão do navegador para o mapa. Recusado com `denied_capability` quando um rótulo de confidencialidade não permite exportação.
`exportImage`	`EmbedExportImageArgs \| void`	`EmbedExportedImage`	read Um PNG ou JPEG do mapa como o leitor o vê, como URL de dados. Recusado com `denied_capability` quando um rótulo de confidencialidade não permite exportação.

Adiciona suas próprias ações ao pop-up da feição. Grupo de política: commands.

Comando	Argumentos	Resolvido com	Observações
`addMenuCommand`	`EmbedMenuCommand`	-	Adiciona sua própria ação ao pop-up da feição. Apenas um título em texto simples e um ID entram no frame, nunca HTML ou script. Clicar nela gera `menuCommandTriggered`.
`removeMenuCommand`	`{ id: string }`	-	Remove uma ação de pop-up que você adicionou.
`getMenuCommands`	-	`Array<{ id: string; title: string }>`	read As ações de pop-up que você adicionou.

Análise

Executa o mecanismo de análise de uma camada, quando o mapa tem um. Grupo de política: analysis.

Comando	Argumentos	Resolvido com	Observações
`getAnalysisOps`	-	`EmbedAnalysisOp[]`	read As operações de análise que este mapa responde, cada uma com sua camada e indicações de argumentos. Vazio quando o mapa não tem mecanismo de análise.
`runAnalysis`	`{ op: string; layerId?: string; args?: Record<string, unknown> }`	`EmbedAnalysisResult`	Executa uma operação de análise. Uma é executada por camada de cada vez; até 4 aguardam (`busy` além disso); 60 por minuto por sessão (`budget_exceeded`). Resultados grandes são limitados e marcados como `truncated`.
`getClock`	`{ layerId?: string } \| void`	`EmbedClockState \| null`	read O relógio de simulação de uma camada de análise, ou null quando ela não tem um.
`setClock`	`{ simSeconds: number; layerId?: string }`	`EmbedClockState`	Move o relógio de simulação de uma camada de análise.

Somente no handle

Estes membros são executados na sua página, e não no mapa, então nunca aparecem em capabilities.commands.

Membro	O que faz
`ready`	Uma promise do descritor de capacidades. É rejeitada com `denied_origin` quando a sua origem não é permitida.
`capabilities`, `protocol`	O que este visualizador responde, depois que isso é conhecido.
`on(name, handler)` / `off(name)`	Inscreve-se em um evento; `on` retorna uma função para cancelar a inscrição.
`render(options)`	Conclui uma incorporação adiada (`deferRender: true`).
`reload()`	Recarrega o frame. As inscrições são restauradas quando a nova sessão é aberta.
`fullscreen()` / `exitFullscreen()`	Coloca o frame em tela inteira. Chame a partir de um manipulador de clique: os navegadores exigem um gesto do usuário na sua página.
`destroy()`	Remove o frame e rejeita tudo o que estiver em andamento com `destroyed`.
`iframe`	O elemento `<iframe>` montado.

Eventos

Nada é enviado até que você se inscreva (handle.on(name, handler) ou a opção events). Todo evento traz um seq válido para a sessão inteira; uma lacuna significa que um evento foi descartado. Os eventos de estado trazem um reason ("user", "command", "bookmark", "tour", "scene" ou "load"), para que uma sincronização bidirecional possa ignorar o próprio eco.

Evento	Payload	Observações
`loaded`	-	O mapa foi renderizado (o `onLoad` da v1).
`rendered`	`{ durationMs: number }`	Primeiro quadro ocioso: os dados do próprio mapa estão na tela. `durationMs` é contado a partir do início do frame.
`viewChanged`	`EmbedViewState & { reason: EmbedChangeReason }`	A câmera se estabilizou (ou, com `continuousView`, se moveu). Com limitação de frequência; o último valor sempre chega.
`visibilityChanged`	`{ visibility: EmbedVisibility; reason: EmbedChangeReason }`	Uma alternância de camada, visual ou mapa base mudou.
`filtersChanged`	`{ filters: EmbedFilterValues; reason: EmbedChangeReason }`	Os valores de filtro da página host mudaram.
`slicerChanged`	`{ slicerId: string; state: EmbedSlicerState; reason: EmbedChangeReason }`	A seleção de uma segmentação mudou.
`selectionChanged`	`{ selection: EmbedSelection; reason: EmbedChangeReason }`	A seleção mudou.
`featureClick`	`EmbedFeatureClick \| null`	O leitor clicou em uma feição (`null` = clicou em uma área vazia do mapa). `fields` contém apenas os campos da dica de ferramenta da camada: o que o leitor já pode ver.
`featureHover`	`EmbedFeatureClick \| null`	O ponteiro entrou em uma feição (`null` = saiu). Desativado, a menos que você se inscreva; intervalo mínimo de 100 ms, e uma saída nunca é atrasada.
`linkClicked`	`{ url: string; layerId?: string; featureKey?: string \| number; buttonId?: string }`	Um hiperlink ou botão de link foi clicado, quando `hyperlinkBehavior` é `raiseEvent` ou `navigateAndRaiseEvent`. Encaminhe-o dentro do seu próprio aplicativo.
`menuCommandTriggered`	`{ commandId: string; layerId: string; featureKey: string \| number; fields: Record<string, unknown> }`	O leitor escolheu uma ação de pop-up que você adicionou com `addMenuCommand`.
`chartSelectionChanged`	`{ chartId: string; datums: EmbedChartDatum[]; reason: EmbedChangeReason }`	Os pontos de dados selecionados de um gráfico mudaram.
`bookmarkApplied`	`{ bookmarkId: string }`	Um indicador foi aplicado, pelo leitor, por um tour ou por você.
`tourStateChanged`	`{ tourId: string \| null; state: "started" \| "keyframe" \| "ended" }`	Um tour começou, chegou a um quadro-chave ou terminou.
`basemapChanged`	`{ basemapId: string }`	O mapa base ativo mudou.
`themeChanged`	`{ mode: string }`	O tema mudou.
`dataStateChanged`	`{ state: "loading" \| "ready" \| "stale" \| "error"; bindingIds?: string[]; reason?: string }`	Os dados ao vivo começaram a carregar, ficaram prontos, ficaram desatualizados ou falharam.
`tokenExpiring`	`{ expiresInMs: number }`	O token de incorporação expira em `expiresInMs` (gerado 60 s antes). Responda com `setToken`.
`error`	`EmbedErrorInfo`	Um erro do visualizador depois que a sessão foi aberta.
`viewerResized`	`{ width: number; height: number }`	O contêiner do mapa mudou de tamanho.
`analysisResult`	`EmbedAnalysisResult & { reason: EmbedChangeReason }`	Uma operação de análise terminou, seja por um clique do leitor ou por um comando da página host.
`clockChanged`	`EmbedClockState & { reason: EmbedChangeReason }`	O relógio do mecanismo de uma camada de análise avançou (com limitação de frequência, `EMBED_LIMITS.clockIntervalMs`).

Códigos de erro

Código	Significado
`unsupported_protocol`	O visualizador e o SDK não têm nenhuma versão de protocolo em comum.
`unsupported_command`	Esta versão do visualizador, esta superfície de incorporação ou este mapa não responde ao comando. Verifique `capabilities.commands` antes.
`denied_capability`	O autor do mapa não ativou o grupo do comando (ou o acesso de leitura), ou um rótulo de confidencialidade recusa uma exportação.
`denied_origin`	A origem da sua página não está nas origens permitidas do mapa, então nenhuma sessão de controle foi aberta.
`invalid_args`	Os argumentos não passaram na validação. `message` diz qual.
`not_ready`	A parte do mapa de que o comando precisa não ficou disponível em 10 segundos. Os comandos enviados cedo ficam retidos, não são recusados, então isso significa que o mapa não conseguiu iniciar. Verifique `onError`.
`unknown_id`	Um ID de camada, indicador, tour, segmentação, gráfico, mapa base ou operação de análise que este mapa não tem.
`undeclared_filter`	`setFilters` indicou um filtro que o autor não declarou. `detail.undeclared` os lista.
`rate_limited`	Mais de 60 comandos em um segundo, ou o limite de taxa do back-end em uma atualização de dados.
`budget_exceeded`	O orçamento de análise por sessão, ou o orçamento de consultas da publicação, foi esgotado.
`too_large`	A mensagem do comando excedeu `EMBED_LIMITS.maxCommandBytes`.
`busy`	Há comandos de análise demais aguardando nessa camada.
`data_error`	O back-end falhou em uma solicitação de dados. Informe o `requestId` em um relato ao suporte.
`auth_required`	O token de incorporação está ausente, expirou ou foi recusado. Forneça `getToken` ou chame `setToken`.
`timeout`	O visualizador não respondeu dentro do tempo limite do comando (no SDK).
`destroyed`	O handle foi destruído, ou o frame foi recarregado, enquanto o comando estava em andamento (no SDK).
`internal`	O comando gerou uma exceção inesperada. `detailedMessage` traz a causa.

Limites

Fixados pelo visualizador (EMBED_LIMITS no SDK). Uma página host não pode aumentá-los, e um autor não pode reduzi-los.

Limite	Valor
Maior mensagem de comando	64 KB; acima disso, é recusada com `too_large`
Maior payload de evento	32 KB; acima disso, é descartado (você vê uma lacuna em `seq`)
Chaves em um `highlight` / `selectByKey`	500
IDs em um resultado de análise	1000; depois, `truncated: true`
Linhas em um resultado de análise	200; depois, `truncated: true`
Comandos de análise por sessão	60 por minuto; depois, `budget_exceeded`
Comandos de análise aguardando em uma camada	4; depois, `busy`
Intervalo de `featureHover`	100 ms (o último valor sempre chega)
Intervalo de `clockChanged`	250 ms (o último valor sempre chega)
Comandos por segundo	60; depois, `rate_limited`