Controllare i filtri dei report

  • Articolo

Quando si incorpora un report di Power BI, è possibile applicare automaticamente filtri durante la fase di caricamento oppure modificare i filtri in modo dinamico dopo il caricamento del report. Ad esempio, è possibile creare un riquadro filtro personalizzato e applicare automaticamente tali filtri ai report per visualizzare le informazioni dettagliate specifiche dell'utente. È anche possibile creare un pulsante che consenta all'utente di applicare filtri al report incorporato.

Sono supportati i tipi di filtro seguenti:

Attributi dell'oggetto filtro

Tutti i tipi di filtro ereditano l'interfaccia IFilter . Gli attributi elencati di seguito sono rilevanti per tutti i tipi di filtro.

interface IFilter {
    $schema: string;
    target: IFilterGeneralTarget;
    filterType: FilterType;
    displaySettings?: IFilterDisplaySettings;
}

SCHEMA

L'attributo $schema definisce il tipo di filtro. Sono disponibili cinque schemi, uno per ogni tipo di filtro:

  • Base - http://powerbi.com/product/schema#basic
  • Avanzate - http://powerbi.com/product/schema#advanced
  • Data relativa - http://powerbi.com/product/schema#relativeDate
  • Tempo relativo - http://powerbi.com/product/schema#relativeTime
  • Primi N - http://powerbi.com/product/schema#topN

Impostazioni schermo

L'attributo displaySettings definisce la modalità di visualizzazione del filtro nel riquadro filtri.

interface IFilterDisplaySettings {
    isLockedInViewMode?: boolean;
    isHiddenInViewMode?: boolean;
    displayName?: string;
}

  • isLockedInViewMode - Viene applicato e visualizzato un filtro bloccato nel riquadro filtro. Il valore del filtro non può essere modificato in modalità di visualizzazione. Impostarlo su true per bloccare il filtro.

  • isHiddenInViewMode - Un filtro nascosto viene applicato al report ma non visualizzato nel riquadro filtro in modalità di visualizzazione. Impostarlo su true per nascondere il filtro.

  • displayName - È possibile visualizzare un filtro nel riquadro filtro con un nome personalizzato. Usare questo attributo per impostare un nome personalizzato per il filtro. Quando il valore non è definito o Null, verrà visualizzato il nome predefinito del filtro (in genere il nome del campo dati filtrato).

Tipo di filtro

L'attributo filterType definisce il tipo del filtro. Usare l'enumerazione seguente, definita nella libreria dei modelli:

enum FilterType {
    Advanced = 0,
    Basic = 1,
    Unknown = 2,
    IncludeExclude = 3,
    RelativeDate = 4,
    TopN = 5,
    Tuple = 6,
    RelativeTime = 7,
}

Destinazione

L'attributo target definisce la destinazione del filtro. Per altre informazioni, vedere Usare le destinazioni per selezionare il campo dati su cui intervenire.

Attributi aggiuntivi per tipo di filtro

Ogni tipo di filtro ha una propria interfaccia con un set diverso di attributi. Le interfacce di filtro fanno parte della libreria powerbi-models .

Filtro di base

Il filtro basic ha un singolo operatore con uno o più valori.

interface IBasicFilter extends IFilter {
    operator: BasicFilterOperators;
    values: (string | number | boolean)[];
    requireSingleSelection?: boolean;
}

  • operator - Per il filtro di base l'operatore può essere uno dei seguenti:

    type BasicFilterOperators = "In" | "NotIn" | "All"

  • values - Matrice di valori per il filtro, tutti i valori devono essere dello stesso tipo.

  • requireSingleSelection - Definisce se è possibile selezionare più valori nel filtro. Se è impostato su true, è possibile selezionare solo un singolo valore.

Ad esempio:

const basicFilter = {
  $schema: "http://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter,
  requireSingleSelection: true
}

Filtro avanzato

Il filtro avanzato ha un singolo operatore logico e una o due condizioni che hanno il proprio operatore e valore.

interface IAdvancedFilter extends IFilter {
    logicalOperator: AdvancedFilterLogicalOperators;
    conditions: IAdvancedFilterCondition[];
}

  • logicalOperator - L'operatore logico può essere uno dei seguenti:

    type AdvancedFilterLogicalOperators = "And" | "Or";

  • conditions - Matrice di condizioni per il filtro avanzato, ogni condizione ha un operator oggetto e un oggetto value.

    interface IAdvancedFilterCondition {
    value?: (string | number | boolean | Date);
    operator: AdvancedFilterConditionOperators;
}

    Gli operatori disponibili per una condizione sono:

    type AdvancedFilterConditionOperators = "None" | "LessThan" | "LessThanOrEqual" | 
"GreaterThan" | "GreaterThanOrEqual" | "Contains" | "DoesNotContain" | "StartsWith" | 
"DoesNotStartWith" | "Is" | "IsNot" | "IsBlank" | "IsNotBlank";

Ad esempio:

const advancedFilter = {
  $schema: "http://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Name"
  },
  logicalOperator: "Or",
  conditions: [
    {
      operator: "Contains",
      value: "Wash"
    },
    {
      operator: "Contains",
      value: "Park"
    }
  ],
  filterType: models.FilterType.AdvancedFilter
}

Nota

Se si crea un AdvancedFilter oggetto con una sola condizione, impostare su logicalOperator"And". L'operatore logico viene ignorato quando viene analizzato da Power BI perché è presente una sola condizione e quando il filtro viene serializzato, l'operatore logico predefinito è "And". In questo modo si garantisce che i filtri restituiti quando si chiama getFilters, corrispondano a quelli impostati usando setFilters.

Filtro Top N

Il filtro Top N include un singolo operatore, un contatore di elementi per la quantità di elementi da visualizzare e l'ordine in base alla destinazione.

interface ITopNFilter extends IFilter {
    operator: TopNFilterOperators;
    itemCount: number;
    orderBy: ITarget;
}

  • operator - L'operatore per il filtro Top N può essere uno dei seguenti:

    type TopNFilterOperators = "Top" | "Bottom";

  • itemCount - Quantità di elementi da visualizzare.

  • orderBy - Campo dati di destinazione in base al quale eseguire l'ordinamento. Per altre informazioni, vedere Usare le destinazioni per selezionare il campo dati su cui intervenire.

Ad esempio:

const topNFilter = {
  $schema: "http://powerbi.com/product/schema#topN",
  target: {
    table: "Store",
    column: "name"
  },
  operator: "Top",
  itemCount: 5,
  orderBy: {
      table: "Product",
      measure: "Count of Product"
   },
  filterType: models.FilterType.TopN
};

Filtri relativi di data e ora relativa

Il filtro relativo per la data e il filtro ora relativa ereditano entrambi dall'interfaccia IRelativeDateTimeFilter :

interface IRelativeDateTimeFilter extends IFilter {
    operator: RelativeDateOperators;
    timeUnitsCount: number;
    timeUnitType: RelativeDateFilterTimeUnit;
}

  • operator - L'operatore per i filtri di data e ora relativi può essere uno dei seguenti:

    enum RelativeDateOperators {
    InLast = 0,
    InThis = 1,
    InNext = 2,
}

  • timeUnitsCount - Quantità di unità di tempo.

  • timeUnitType - Definisce l'unità di tempo in cui viene utilizzato il filtro.

    enum RelativeDateFilterTimeUnit {
    Days = 0,
    Weeks = 1,
    CalendarWeeks = 2,
    Months = 3,
    CalendarMonths = 4,
    Years = 5,
    CalendarYears = 6,
    Minutes = 7,
    Hours = 8
}

    Nella tabella seguente sono elencate le ore di unità supportate dai filtri relativi di data e ora relativa.

    Unità di tempo Data relativa Tempo relativo
    Giorni ✔ ✖
    Settimane ✔ ✖
    CalendarWeeks ✔ ✖
    Months ✔ ✖
    CalendarMonths ✔ ✖
    Anni ✔ ✖
    CalendarYears ✔ ✖
    Minuti ✖ ✔
    Ore ✖ ✔

  • includeToday - Accetta un valore booleano che specifica se includere il giorno corrente nel filtro.

    interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}

    Nota

    includeToday è supportato solo dal filtro data relativo.

Esempio di filtro data relativo:

const relativeDateFilter = {
  $schema: "http://powerbi.com/product/schema#relativeDate",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 30,
  timeUnitType: RelativeDateFilterTimeUnit.Days,
  includeToday: true,
  filterType: models.FilterType.RelativeDate
};

Esempio di filtro tempo relativo:

const relativeTimeFilter = {
  $schema: "http://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 12,
  timeUnitType: models.RelativeDateFilterTimeUnit.Hours,
  filterType: models.FilterType.RelativeTime
};

API filtri

Usare i metodi seguenti per ottenere e aggiornare i filtri applicati a un report:

Ottenere filtri

Usare getFilters per ottenere tutti i filtri per uno degli oggetti seguenti:

  • Report
  • Pagina
  • Oggetto visivo
getFilters(): Promise<IFilter[]>

Aggiornare i filtri

Usare updateFilters per aggiungere, sostituire o rimuovere filtri nell'oggetto (report, pagina o oggetto visivo). Riceve un'operazione e una matrice di filtri facoltativa.

updateFilters(operation: models.FiltersOperations, filters?: models.IFilter[]): Promise<IHttpPostMessageResponse<void>>

Operazione filtri

Quando si chiama updateFilters è necessario passare l'operazione di filtro da preformare. Le operazioni disponibili sono:

  • RemoveAll - Rimuove tutti i filtri a livello di filtro.
  • ReplaceAll - Sostituisce tutti i filtri esistenti a livello di filtro con i filtri specificati.
  • Add - Aggiunge i filtri specificati a livello di filtro (oltre ai filtri esistenti).
  • Replace - Sostituisce un filtro esistente con un determinato filtro solo se entrambi i filtri si applicano allo stesso campo dati. Se è presente un determinato filtro che non sostituisce un filtro esistente, verrà aggiunto.

Nota

Quando si chiama l'API con RemoveAll, l'argomento filtri deve essere undefined. Per qualsiasi altra operazione, deve essere definita.

Livelli di filtri

L'aggiornamento e l'acquisizione dei filtri possono essere eseguiti a tre livelli. I filtri a livello diverso sono indipendenti e l'aggiornamento dei filtri a un livello non cambierà. Ad esempio, la rimozione di un filtro di pagina non la rimuove da altre pagine del report.

I livelli supportati per i filtri sono:

  • Report : i filtri vengono applicati a tutte le pagine del report.
  • Pagina : i filtri vengono applicati alla pagina del report corrente.
  • Oggetto visivo : i filtri vengono applicati a un oggetto visivo specifico.

Nota

Solo i filtri a livello di oggetto visivo supportano il tipo di ITopNFilter filtro.

Filtri a livello di report

Per ottenere o aggiornare i filtri che si applicano a tutte le pagine del report, chiamare l'API pertinente nell'oggetto report. Ad esempio:

Ottenere i filtri del report

Ottenere i filtri applicati a tutte le pagine.

let reportFilters = await report.getFilters();

Aggiungere nuovi filtri ai filtri del report

Aggiunta di nuovi filtri, insieme ai filtri esistenti, per tutte le pagine.

await report.updateFilters(models.FiltersOperations.Add, filtersArray);

Rimuovere i filtri del report

Rimuovere i filtri applicati a tutte le pagine.

await report.updateFilters(models.FiltersOperations.RemoveAll);

Filtri a livello di pagina

Per ottenere o aggiornare i filtri a livello di pagina, eseguire le operazioni seguenti:

  1. Ottenere l'oggetto pagina per la pagina di destinazione. Per altre informazioni, vedere Ottenere pagine e oggetti visivi.
  2. Nell'oggetto pagina chiamare l'API pertinente.

Ottenere i filtri di pagina

Ottenere i filtri applicati a una pagina specifica.

let reportFilters = await page.getFilters();

Sostituire tutti i filtri di pagina

Sostituzione di tutti i filtri esistenti applicati a una pagina specifica, con un nuovo set di filtri.

await page.updateFilters(models.FiltersOperations.ReplaceAll, filtersArray);

Rimuovere i filtri di pagina

Rimozione dei filtri applicati a una pagina specifica.

await page.updateFilters(models.FiltersOperations.RemoveAll);

Filtri a livello di oggetto visivo

Per ottenere o aggiornare i filtri a livello di oggetto visivo, eseguire le operazioni seguenti:

  1. Ottenere l'oggetto visivo per l'oggetto visivo di destinazione. Per altre informazioni, vedere Ottenere pagine e oggetti visivi.
  2. Nell'oggetto visivo chiamare l'API pertinente.

Ottenere i filtri visivi

Ottenere i filtri applicati a un oggetto visivo specifico.

let reportFilters = await visual.getFilters();

Sostituire filtri visivi con la stessa destinazione

Sostituzione dei filtri di un oggetto visivo specifico. Se esiste un filtro con lo stesso campo dati di destinazione di un determinato filtro, viene sostituito dal filtro specificato. I filtri specificati che non corrispondono a alcun filtro esistente vengono aggiunti.

await visual.updateFilters(models.FiltersOperations.Replace, filtersArray);

Rimuovere i filtri visivi

Rimozione dei filtri applicati a un oggetto visivo specifico.

await visual.updateFilters(models.FiltersOperations.RemoveAll);

Limitazioni

  • Quando si compila un filtro avanzato possono verificarsi più di due condizioni, il comportamento non definito.

  • IncludeExclude e Tuple i tipi di filtro non sono supportati.

  • Le destinazioni di filtro tuple e gerarchia non sono supportate.

Passaggi successivi