Idioma
Português

Visão geral da Embed API

A Embed API permite que a página que hospeda um Icon Map incorporado controle o mapa com JavaScript e receba respostas dele. Se você já usou a biblioteca cliente do Power BI Embedded, a ideia é a mesma, aplicada a mapas: um SDK pequeno, um handle, comandos que retornam promises e eventos aos quais você pode se inscrever.

Esta seção é para os desenvolvedores que constroem a página host. Se você é o autor do mapa e quer publicá-lo ou incorporá-lo, comece por Publicação e compartilhamento e Incorporação de mapas.

const map = IconMapEmbed.embed(document.getElementById("map"), { publishId: "pub_..." });
await map.ready;

await map.flyTo({ center: [-0.12, 51.5], zoom: 11 });
await map.selectByKey({ layerId: "assets", field: "asset_id", keys: ["41B"], zoomTo: true });

map.on("featureClick", (feature) => feature && openAssetPanel(feature.fields));

O que você pode fazer

Área Exemplos
Câmera Ler a vista, saltar ou voar até um local, enquadrar uma caixa delimitadora ou uma camada inteira, limitar o deslocamento a uma área
Camadas Listar as camadas, mostrá-las e ocultá-las, ler cada alternância que o leitor tem (rótulos, sombreamento, gráficos e outros visuais)
Filtros Descobrir os filtros que o autor declarou e defini-los (incluindo intervalos numéricos e "últimos 30 dias"), atualizar dados ao vivo
Segmentações de dados Ler e definir as segmentações do leitor, listar os valores que uma segmentação oferece
Seleção Selecionar feições pelas suas próprias chaves ("ativo 41B"), realçar sem selecionar, aplicar filtro cruzado a partir de um gráfico
Cenas Capturar a vista inteira como um único objeto, restaurá-la depois, aplicar os indicadores do autor, reproduzir tours
Apresentação Alternar entre os mapas base publicados, ocultar os controles do próprio mapa, usar o modo escuro, ler a legenda como dados, exportar uma imagem
Comandos de pop-up Adicionar sua própria ação ao pop-up da feição ("Abrir uma ordem de serviço para este ativo")
Análise Executar o mecanismo de análise de uma camada e receber os resultados, nos mapas que têm um
Eventos Mudanças de vista, cliques em feições, seleção, filtros, segmentações, cliques em links, estado dos dados, expiração do token

O guia de comandos percorre esses recursos com exemplos; a referência da API lista cada comando, evento, código de erro e limite.

Como funciona

O SDK monta o mapa como um <iframe> e se comunica com ele por postMessage. Nada do mapa é executado na sua página, e nada da sua página é executado no mapa.

  1. Sua página chama embed(). O SDK cria o frame e espera que ele avise que está pronto.
  2. Os dois lados combinam uma versão de protocolo, e o mapa verifica a origem da sua página na lista de sites que o autor permitiu.
  3. Se você tiver permissão, o mapa responde com um descritor de capacidades: os comandos e eventos que este mapa atende. await map.ready é resolvido com ele.
  4. A partir daí, cada chamada de método é uma mensagem para o mapa e uma resposta de volta.

Você não precisa sincronizar nada. Os comandos chamados antes de o mapa terminar de iniciar ficam retidos e são respondidos assim que a parte do mapa de que precisam estiver disponível.

Duas formas de incorporar, uma só API

Mapa publicado Incorporação para sua organização
Quem visualiza Qualquer pessoa a quem você der a página, sem conta do Fabric Colegas, cada um conectado com a própria conta corporativa
Dados Congelados ou ao vivo, por meio da publicação Ao vivo, lidos como cada leitor, de modo que as permissões do Fabric e a segurança em nível de linha se aplicam
Ponto de entrada embed(element, { publishId }) embedForOrganization(element, { mapItem })
Quem pode controlá-lo Os sites em Allowed origins da publicação Os sites nas origens de Embedding for your organization do item

Ambos retornam o mesmo handle, com os mesmos métodos. Alguns grupos existem só em mapas publicados (filtros declarados e atualização de dados), porque um item ao vivo não tem uma publicação em que declará-los. capabilities.commands sempre informa exatamente o que você tem.

O que o autor controla

O controle por incorporação é ativado por mapa, pelo autor, na caixa de diálogo de publicação:

  • Allowed origins. Só páginas nesses sites podem abrir uma sessão de controle. Um mapa sem origens permitidas ainda pode ser exibido, mas não pode ser controlado.
  • Grupos de comandos. Câmera, camadas, filtros, segmentações, seleção, cenas, apresentação, comandos de pop-up, atualização de dados, análise e leitura de estado e eventos. Todos vêm ativados por padrão; o autor pode desativar qualquer um.

As duas configurações fazem parte da publicação assinada, portanto não podem ser ampliadas editando arquivos nem por nada que sua página envie.

O que a API não faz

Estes limites são deliberados e permanentes. Vale a pena conhecê-los antes de planejar em torno deles:

  • Nada que um leitor não pudesse fazer clicando. Não há comando que receba uma URL, uma consulta, um estilo ou uma definição de camada. Para mostrar outro mapa, publique outro mapa.
  • Nada que o leitor não possa ver. featureClick traz apenas os campos da dica de ferramenta da camada. Não há leitura em massa dos dados por trás de uma camada, nem acesso à configuração, às fontes de dados ou às consultas do mapa.
  • Somente filtros declarados. setFilters aceita os filtros que o autor declarou e nada mais; os valores são vinculados como parâmetros no servidor, nunca colados em uma consulta.
  • Visibilidade, não estilo. Você pode mostrar e ocultar uma camada. Não pode mudar a cor nem o estilo dela.
  • Os rótulos de confidencialidade são respeitados. exportImage e print são recusados quando um rótulo nos dados do mapa não permite exportação.

Próximas etapas