Filtros e atualização de dados

Sua página pode filtrar os dados que um mapa publicado mostra: um cliente, uma região, os últimos 30 dias. Isso é feito por meio de filtros declarados: um conjunto fixo de entradas nomeadas e tipadas que o autor do mapa escolheu no momento da publicação.

Por que os filtros são declarados

Um filtro é o único lugar em que um valor vindo da sua página chega aos dados do mapa. Por isso a regra é rígida, e é a mesma para mapas de instantâneo e ao vivo:

• Você só pode indicar um filtro que o autor declarou. Qualquer outro é rejeitado antes de ser aplicado.
• Os valores são verificados em relação ao tipo declarado e, em mapas ao vivo, são vinculados como parâmetros de consulta no servidor, nunca colados em uma consulta.
• Um filtro restringe o que o mapa mostra. Ele nunca consegue alcançar dados que a publicação ainda não inclua.

É isso que torna seguro usar valores de filtro vindos de uma URL ou da sessão de um usuário. Isso não é uma barreira de segurança entre usuários: qualquer pessoa que consiga abrir o mapa pode alterar o filtro. Para restringir o que um usuário específico pode ver, use um mapa protegido por token com segurança em nível de linha, ou uma incorporação organizacional.

Descubra os 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" }
]

Construa sua interface de filtros a partir disso, em vez de fixar nomes no código: assim ela continua funcionando quando o autor adiciona um filtro, e você sabe quais operadores cada um aceita.

Autores: quando um mapa é publicado, o Icon Map declara automaticamente um filtro para cada coluna que uma das segmentações do mapa consegue alcançar. Portanto, para dar a uma página host um filtro em uma coluna, adicione uma segmentação nessa coluna e publique de novo. Sua página pode então ocultar essa segmentação dos leitores. Veja Bloquear ou ocultar a segmentação correspondente.

Defina filtros

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

Defina-os na montagem para evitar carregar primeiro os dados sem filtro:

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

Formatos de valor

Datas relativas recebem operator "inLast", "inThis" ou "inNext"; unit "days", "weeks", "months" ou "years"; e um includeToday opcional. A janela é calculada em relação à data de hoje sempre que o filtro é aplicado.

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

Altere um filtro de cada vez

updateFilters altera alguns filtros sem repetir os demais, no mesmo modelo do updateFilters do 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 remover um único filtro, defina os valores que você quer manter:

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

Bloquear ou ocultar a segmentação correspondente

Quando sua página define um filtro, o leitor ainda pode ver no mapa uma segmentação para a mesma coluna e tentar alterá-la. display resolve isso:

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

locked e hidden removem da vista do leitor a segmentação vinculada à coluna desse filtro, para que o que a sua página fixou continue fixo. displayName a renomeia.

Erros

filtersChanged é disparado após cada alteração, com um reason.

Atualize dados ao vivo

Em um mapa publicado com dados ao vivo, refreshData executa as consultas novamente, ignorando o cache:

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

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

Em um mapa de instantâneo, o comando é resolvido com uma lista vazia: não há nada para executar de novo até que o autor publique outra vez. capabilities.map.dataMode informa qual dos dois você tem: "live", "snapshot" ou "mixed".

Cada atualização consome a capacidade do Fabric do proprietário do mapa, por isso tem limite de taxa e conta para o orçamento de consultas da publicação. Espere rate_limited ou budget_exceeded se a sua página atualizar em um timer curto; o autor também pode desativar o grupo Data refresh, o que o servidor impõe, além do próprio mapa.