Controllare i filtri dei report

Quando si incorpora un report di Power BI, è possibile applicare filtri automaticamente 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 applicarli automaticamente 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:

• basic - IBasicFilter
• - IAdvancedFilter avanzate
• primi N - ITopNFilter
• data relativa - IRelativeDateFilter
• tempo relativo - IRelativeTimeFilter

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:

• basic - https://powerbi.com/product/schema#basic
• - https://powerbi.com/product/schema#advanced avanzate
• data relativa - https://powerbi.com/product/schema#relativeDate
• tempo relativo - https://powerbi.com/product/schema#relativeTime
• primi N - https://powerbi.com/product/schema#topN

Impostazioni di visualizzazione

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

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

• isLockedInViewMode: viene applicato un filtro bloccato e visualizzato 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,
}

Bersaglio

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

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 di powerbi-models.

Filtro di base

filtro Basic dispone di 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.

Per esempio:

const basicFilter = {
  $schema: "https://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

di filtro avanzato ha un singolo operatore logico e una o due condizioni con un 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 e un 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";
  

Per esempio:

const advancedFilter = {
  $schema: "https://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
}

Filtro N superiore

filtro Top N include un singolo operatore, un contatore degli 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 da usare su.

Per esempio:

const topNFilter = {
  $schema: "https://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 di filtro di data relativa 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 usato 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 elencati gli orari di unità supportati dai filtri relativi di data e ora relativa.

  Unità di tempo	Data relativa	Tempo relativo
  Giorni	✔	✖
  Settimane	✔	✖
  CalendarWeeks	✔	✖
  Mesi	✔	✖
  CalendarMonths	✔	✖
  Anni	✔	✖
  CalendarYears	✔	✖
  Verbale	✖	✔
  Orario	✖	✔

• 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 di data relativo .

Esempio di filtro relativo per la data:

const relativeDateFilter = {
  $schema: "https://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 temporale relativo:

const relativeTimeFilter = {
  $schema: "https://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 di filtri

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

• Get filters - getFilters
• Aggiornare i filtri- updateFilters.

Ottenere i filtri

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

• Rapporto
• Pagina
• Visivo

getFilters(): Promise<IFilter[]>

Aggiornare i filtri

Utilizzare 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 si vuole eseguire la premaschera. 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.

Livelli di filtro

L'aggiornamento e il recupero dei filtri possono essere eseguiti a tre livelli. I filtri a livello diverso sono indipendenti e l'aggiornamento dei filtri su un livello non cambierà. Ad esempio, rimuovendo un filtro di pagina, non viene rimosso 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.
• Visual: i filtri vengono applicati a un oggetto visivo specifico.

Filtri a livello di report

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

Ottenere i filtri del report

Recupero dei 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 della pagina

Recupero dei 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. Ottiene 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

Recupero dei filtri applicati a un oggetto visivo specifico.

let reportFilters = await visual.getFilters();

Sostituire i 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 ad 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);

Considerazioni e limitazioni

• L'uso di più di due condizioni durante la creazione di un di filtro avanzato può causare un comportamento indefinito.

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

• Le destinazioni di filtro della tupla e della gerarchia non sono supportate.

Contenuto correlato

• Configurare le impostazioni del report
• Controllare i filtri dei dati dei report
• Personalizzare un layout di report