Filtros y actualización de datos

Su página puede filtrar los datos que muestra un mapa publicado: a un cliente, una región, los últimos 30 días. Lo hace mediante filtros declarados: un conjunto fijo de entradas con nombre y tipo que el autor del mapa eligió al publicarlo.

Por qué se declaran los filtros

Un filtro es el único punto en el que un valor de su página llega a los datos del mapa. Por eso la regla es estricta, y es la misma para mapas instantáneos y en directo:

• Solo puede indicar un filtro que el autor haya declarado. Cualquier otro se rechaza antes de aplicarse.
• Los valores se comprueban con el tipo declarado y, en los mapas en directo, se enlazan como parámetros de consulta en el servidor; nunca se insertan en una consulta.
• Un filtro restringe lo que muestra el mapa. Nunca puede llegar a datos que la publicación no incluya ya.

Esto es lo que hace seguro tomar valores de filtro de una URL o de la sesión de un usuario. No es un límite de seguridad entre usuarios: cualquiera que pueda abrir el mapa puede cambiar el filtro. Para restringir lo que puede ver un usuario concreto, use un mapa protegido con token con seguridad de nivel de fila, o una inserción organizativa.

Descubrir los filtros

const schema = await map.getFilterSchema();

[
  { name: "region",   type: "stringList", operators: ["in"],                 label: "Region", column: "Region", values: ["EMEA", "AMER", "APAC"] },
  { name: "revenue",  type: "number",     operators: ["in", "between"],      label: "Revenue" },
  { name: "period",   type: "dateRange",  operators: ["between", "relative"], label: "Order date" }
]

Cree su interfaz de filtrado a partir de esto en lugar de codificar los nombres de forma fija: así seguirá funcionando cuando el autor añada un filtro, y le indica qué operadores acepta cada uno.

Para autores: al publicar un mapa, Icon Map declara automáticamente un filtro por cada columna a la que llega alguna de sus segmentaciones. Así que, para dar a una página host un filtro sobre una columna, añada una segmentación sobre esa columna y vuelva a publicar. Después, su página puede ocultar esa segmentación a los lectores: consulte Bloquear u ocultar la segmentación correspondiente.

Establecer filtros

await map.setFilters({ region: ["EMEA", "APAC"] });          // replaces all your filter values
await map.clearFilters();
const current = await map.getFilters();

Establézcalos al montar el mapa para no cargar primero datos sin filtrar:

embed(el, { publishId, filters: { region: ["EMEA"] } });

Formas de los valores

Las fechas relativas aceptan operator "inLast", "inThis" o "inNext"; unit "days", "weeks", "months" o "years"; y un includeToday opcional. El intervalo se calcula respecto a la fecha de hoy cada vez que se aplica el filtro.

await map.setFilters({ period: { operator: "inLast", count: 30, unit: "days", includeToday: true } });

Cambiar un filtro cada vez

updateFilters cambia algunos filtros sin volver a indicar el resto: el mismo modelo que updateFilters de Power BI.

await map.updateFilters({ operation: "add",        filters: { region: ["EMEA"] } });   // merge into what is set
await map.updateFilters({ operation: "replace",    filters: { region: ["APAC"] } });   // overwrite these names only
await map.updateFilters({ operation: "replaceAll", filters: { region: ["AMER"] } });   // same as setFilters
await map.updateFilters({ operation: "removeAll" });

Para quitar un único filtro, establezca los valores que quiere conservar:

const { region, ...rest } = await map.getFilters();
await map.setFilters(rest);

Bloquear u ocultar la segmentación correspondiente

Cuando su página establece un filtro, el lector puede seguir viendo en el mapa una segmentación sobre la misma columna e intentar cambiarla. display se ocupa de ello:

await map.updateFilters({
  operation: "replace",
  filters: { region: ["EMEA"] },
  display: { region: { locked: true } },
});

locked y hidden quitan ambos de la vista del lector la segmentación enlazada a la columna de ese filtro, de modo que lo que fijó su página permanece fijado. displayName le cambia el nombre.

Errores

filtersChanged se desencadena después de cada cambio, con un reason.

Actualizar los datos en directo

En un mapa publicado con datos en directo, refreshData vuelve a ejecutar las consultas sin pasar por la caché:

const { refreshed } = await map.refreshData();                       // every live dataset
await map.refreshData({ bindingIds: ["orders"] });                   // just one

map.on("dataStateChanged", ({ state, bindingIds }) => showSpinner(state === "loading"));

En un mapa instantáneo se resuelve con una lista vacía: no hay nada que volver a ejecutar hasta que el autor publique de nuevo. capabilities.map.dataMode le indica cuál tiene: "live", "snapshot" o "mixed".

Cada actualización consume capacidad de Fabric del propietario del mapa, por lo que tiene un límite de frecuencia y cuenta para el presupuesto de consultas de la publicación. Espere rate_limited o budget_exceeded si su página actualiza con un temporizador muy corto; el autor también puede desactivar el grupo Data refresh, algo que aplica el servidor además del mapa.