Idioma
Español

Información general de la Embed API

La Embed API permite que la página que hospeda un Icon Map insertado controle el mapa desde JavaScript y reciba respuestas de él. Si ha usado la biblioteca cliente de Power BI Embedded, es la misma idea aplicada a mapas: un SDK pequeño, un identificador (handle), comandos que devuelven promesas y eventos a los que suscribirse.

Esta sección está dirigida a los desarrolladores que crean la página host. Si es el autor del mapa y quiere publicarlo o insertarlo, empiece por Publicar y compartir e Insertar 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));

Qué se puede hacer

Área Ejemplos
Cámara Leer la vista, saltar o volar a un lugar, encuadrar un rectángulo delimitador o una capa completa, limitar el desplazamiento a una zona
Capas Enumerar las capas, mostrarlas y ocultarlas, leer todos los conmutadores que tiene el lector (etiquetas, sombreado, gráficos y otros objetos visuales)
Filtros Descubrir los filtros que declaró el autor y establecerlos (incluidos intervalos numéricos y "últimos 30 días"), actualizar datos en directo
Segmentaciones Leer y establecer las segmentaciones del lector, enumerar los valores que ofrece una segmentación
Selección Seleccionar entidades por sus propias claves ("activo 41B"), resaltar sin seleccionar, aplicar un filtro cruzado desde un gráfico
Escenas Capturar toda la vista como un único objeto, restaurarla más tarde, aplicar los marcadores del autor, reproducir recorridos
Presentación Cambiar entre los mapas base publicados, ocultar los controles propios del mapa, pasar al modo oscuro, leer la leyenda como datos, exportar una imagen
Comandos de la ventana emergente Añadir una acción propia a la ventana emergente de la entidad ("Abrir una orden de trabajo para este activo")
Análisis Ejecutar el motor de análisis de una capa y recibir sus resultados, en los mapas que lo tienen
Eventos Cambios de vista, clics en entidades, selección, filtros, segmentaciones, clics en vínculos, estado de los datos, caducidad del token

La guía de comandos los recorre con ejemplos; la referencia de la API enumera todos los comandos, eventos, códigos de error y límites.

Cómo funciona

El SDK monta el mapa como un <iframe> y se comunica con él mediante postMessage. Nada del mapa se ejecuta en su página, y nada de su página se ejecuta en el mapa.

  1. Su página llama a embed(). El SDK crea el marco y espera a que este indique que está listo.
  2. Las dos partes acuerdan una versión de protocolo, y el mapa comprueba el origen de su página con la lista de sitios que su autor permitió.
  3. Si tiene permiso, el mapa responde con un descriptor de capacidades: los comandos y eventos que este mapa atenderá. await map.ready se resuelve con él.
  4. A partir de ahí, cada llamada a un método es un mensaje al mapa y una respuesta de vuelta.

No es necesario sincronizar nada. Los comandos que se llaman antes de que el mapa termine de iniciarse se retienen y se responden en cuanto existe la parte del mapa que necesitan.

Dos formas de insertar, una sola API

Mapa publicado Inserción para su organización
Quién lo ve Cualquier persona a la que dé la página, sin cuenta de Fabric Compañeros, cada uno con la sesión iniciada con su propia cuenta profesional
Datos Congelados o en directo, a través de la publicación En directo, leídos como cada espectador, de modo que se aplican los permisos de Fabric y la seguridad de nivel de fila
Punto de entrada embed(element, { publishId }) embedForOrganization(element, { mapItem })
Quién puede controlarlo Los sitios incluidos en los Allowed origins de la publicación Los sitios incluidos en los orígenes de Embedding for your organization del elemento

Ambos devuelven el mismo identificador con los mismos métodos. Algunos grupos existen solo en los mapas publicados (los filtros declarados y la actualización de datos), porque un elemento en directo no tiene una publicación en la que declararlos. capabilities.commands siempre indica exactamente de qué dispone.

Qué controla el autor

El control de la inserción lo activa el autor, mapa por mapa, en el cuadro de diálogo de publicación:

  • Allowed origins. Solo las páginas de estos sitios pueden abrir una sesión de control. Un mapa sin orígenes permitidos se puede mostrar igualmente, pero no se puede controlar.
  • Grupos de comandos. Cámara, capas, filtros, segmentaciones, selección, escenas, presentación, comandos de la ventana emergente, actualización de datos, análisis y lectura de estado y eventos. Todos están activados de forma predeterminada; el autor puede desactivar cualquiera.

Ambas opciones forman parte de la publicación firmada, por lo que no se pueden ampliar editando archivos ni con nada que envíe su página.

Qué no hará la API

Son límites deliberados y permanentes, útiles de conocer antes de diseñar en torno a ellos:

  • Nada que un lector no pueda hacer con clics. No hay ningún comando que acepte una URL, una consulta, un estilo o una definición de capa. Para mostrar otro mapa, publique otro mapa.
  • Nada que el lector no pueda ver. featureClick solo lleva los campos de información sobre herramientas de la capa. No hay lectura masiva de los datos que hay detrás de una capa, ni acceso a la configuración, los orígenes de datos o las consultas del mapa.
  • Solo filtros declarados. setFilters acepta los filtros que declaró el autor y nada más; los valores se enlazan como parámetros en el servidor y nunca se insertan en una consulta.
  • Visibilidad, no estilo. Puede mostrar y ocultar una capa. No puede cambiar su color ni su estilo.
  • Se respetan las etiquetas de confidencialidad. exportImage y print se rechazan cuando una etiqueta de los datos del mapa no permite la exportación.

Pasos siguientes