Filtres et actualisation des données

Votre page peut filtrer les données affichées par une carte publiée : sur un client, une région, les 30 derniers jours. Elle le fait au moyen de filtres déclarés : un ensemble fixe d'entrées nommées et typées, choisies par l'auteur de la carte au moment de la publication.

Pourquoi les filtres sont déclarés

Un filtre est le seul endroit où une valeur provenant de votre page atteint les données de la carte. La règle est donc stricte, et elle est la même pour les cartes instantanées et les cartes en direct :

• Vous ne pouvez nommer qu'un filtre déclaré par l'auteur. Tout le reste est rejeté avant d'être appliqué.
• Les valeurs sont vérifiées par rapport au type déclaré et, sur les cartes en direct, liées comme paramètres de requête sur le serveur, jamais collées dans une requête.
• Un filtre restreint ce que la carte affiche. Il ne peut jamais atteindre des données que la publication ne contient pas déjà.

C'est ce qui permet de reprendre sans risque des valeurs de filtre depuis une URL ou la session d'un utilisateur. Ce n'est pas une frontière de sécurité entre utilisateurs : toute personne qui peut ouvrir la carte peut modifier le filtre. Pour restreindre ce qu'un utilisateur donné peut voir, utilisez une carte protégée par jeton avec sécurité au niveau des lignes, ou une incorporation organisationnelle.

Découvrir les filtres

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

Construisez votre interface de filtrage à partir de ce schéma plutôt que de coder les noms en dur : elle continuera de fonctionner lorsque l'auteur ajoutera un filtre, et elle vous indique les opérateurs acceptés par chacun.

Auteurs : lors de la publication d'une carte, Icon Map déclare automatiquement un filtre pour chaque colonne que l'un de ses segments peut atteindre. Pour proposer à une page hôte un filtre sur une colonne, ajoutez donc un segment sur cette colonne et publiez à nouveau. Votre page peut ensuite masquer ce segment aux lecteurs : voir Verrouiller ou masquer le segment correspondant.

Définir des filtres

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

Définissez-les au montage pour éviter de charger d'abord des données non filtrées :

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

Formes des valeurs

Les dates relatives acceptent operator "inLast", "inThis" ou "inNext" ; unit "days", "weeks", "months" ou "years" ; et un includeToday facultatif. La période est recalculée par rapport à la date du jour chaque fois que le filtre est appliqué.

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

Modifier un filtre à la fois

updateFilters modifie certains filtres sans redéfinir les autres, selon le même modèle que updateFilters dans 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" });

Pour supprimer un seul filtre, définissez les valeurs que vous voulez conserver :

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

Verrouiller ou masquer le segment correspondant

Lorsque votre page définit un filtre, le lecteur peut encore voir dans la carte un segment portant sur la même colonne et essayer de le modifier. display règle ce problème :

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

locked et hidden retirent tous deux de la vue du lecteur le segment lié à la colonne de ce filtre : ce que votre page a fixé reste fixé. displayName le renomme.

Erreurs

filtersChanged est déclenché après chaque modification, avec une reason.

Actualiser les données en direct

Sur une carte publiée avec des données en direct, refreshData réexécute les requêtes sans passer par le cache :

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

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

Sur une carte instantanée, la commande se résout avec une liste vide : il n'y a rien à réexécuter tant que l'auteur ne publie pas à nouveau. capabilities.map.dataMode vous indique de quel type de carte il s'agit : "live", "snapshot" ou "mixed".

Chaque actualisation consomme la capacité Fabric du propriétaire de la carte : elle est donc soumise à une limite de débit et décomptée du budget de requêtes de la publication. Attendez-vous à rate_limited ou budget_exceeded si votre page actualise à intervalles rapprochés ; l'auteur peut aussi désactiver le groupe Data refresh, ce que le serveur applique au même titre que la carte.