Filter und Datenaktualisierung

Ihre Seite kann die Daten filtern, die eine veröffentlichte Karte zeigt: auf einen Kunden, eine Region, die letzten 30 Tage. Das geschieht über deklarierte Filter, einen festen Satz benannter, typisierter Eingaben, die der Autor der Karte beim Veröffentlichen gewählt hat.

Warum Filter deklariert werden

Ein Filter ist die einzige Stelle, an der ein Wert von Ihrer Seite die Daten der Karte erreicht. Die Regel ist daher streng, und sie gilt für Snapshot- und Live-Karten gleichermaßen:

• Sie können nur einen Filter benennen, den der Autor deklariert hat. Alles andere wird abgelehnt, bevor es angewendet wird.
• Werte werden gegen den deklarierten Typ geprüft und bei Live-Karten auf dem Server als Abfrageparameter gebunden, niemals in eine Abfrage eingefügt.
• Ein Filter schränkt ein, was die Karte zeigt. Er kann nie Daten erreichen, die die Veröffentlichung nicht bereits enthält.

Deshalb ist es sicher, Filterwerte aus einer URL oder der Sitzung eines Benutzers zu übernehmen. Eine Sicherheitsgrenze zwischen Benutzern ist es nicht: Jeder, der die Karte öffnen kann, kann den Filter ändern. Um einzuschränken, was ein bestimmter Benutzer sehen darf, verwenden Sie eine Karte mit Token-Schutz und Sicherheit auf Zeilenebene oder eine organisationsinterne Einbettung.

Die Filter ermitteln

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

Bauen Sie Ihre Filteroberfläche daraus auf, statt Namen fest zu codieren. Dann funktioniert sie weiter, wenn der Autor einen Filter hinzufügt, und Sie erfahren, welche Operatoren jeder Filter akzeptiert.

Für Autoren: Beim Veröffentlichen einer Karte deklariert Icon Map automatisch einen Filter für jede Spalte, die einer ihrer Datenschnitte erreichen kann. Um einer einbettenden Seite einen Filter auf eine Spalte zu geben, fügen Sie also einen Datenschnitt auf diese Spalte hinzu und veröffentlichen erneut. Ihre Seite kann diesen Datenschnitt dann vor den Betrachtern ausblenden, siehe Den passenden Datenschnitt sperren oder ausblenden.

Filter setzen

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

Setzen Sie sie beim Einbinden, um nicht zuerst ungefilterte Daten zu laden:

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

Formen der Werte

Relative Daten nehmen als operator "inLast", "inThis" oder "inNext", als unit "days", "weeks", "months" oder "years" sowie optional includeToday. Der Zeitraum wird bei jedem Anwenden des Filters anhand des heutigen Datums berechnet.

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

Einen Filter nach dem anderen ändern

updateFilters ändert einige Filter, ohne die übrigen erneut anzugeben. Es ist dasselbe Modell wie updateFilters in 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" });

Um einen einzelnen Filter zu entfernen, setzen Sie die Werte, die Sie behalten möchten:

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

Den passenden Datenschnitt sperren oder ausblenden

Wenn Ihre Seite einen Filter setzt, sieht der Betrachter in der Karte möglicherweise noch einen Datenschnitt für dieselbe Spalte und versucht, ihn zu ändern. Dafür gibt es display:

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

locked und hidden entfernen beide den Datenschnitt, der an die Spalte dieses Filters gebunden ist, aus der Ansicht des Betrachters. Was Ihre Seite festgelegt hat, bleibt also festgelegt. displayName benennt ihn um.

Fehler

filtersChanged wird nach jeder Änderung ausgelöst, mit einem reason.

Livedaten aktualisieren

Bei einer Karte, die mit Live-Daten veröffentlicht wurde, führt refreshData die Abfragen am Cache vorbei erneut aus:

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

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

Bei einer Snapshot-Karte wird der Befehl mit einer leeren Liste aufgelöst: Bis der Autor erneut veröffentlicht, gibt es nichts erneut auszuführen. capabilities.map.dataMode sagt Ihnen, was Sie haben: "live", "snapshot" oder "mixed".

Jede Aktualisierung verbraucht Fabric-Kapazität des Kartenbesitzers. Sie ist daher ratenbegrenzt und wird auf das Abfragebudget der Veröffentlichung angerechnet. Rechnen Sie mit rate_limited oder budget_exceeded, wenn Ihre Seite in kurzen Abständen aktualisiert. Der Autor kann außerdem die Gruppe Data refresh deaktivieren; das erzwingt dann der Server ebenso wie die Karte.