Filtros de relatório de controle

Ao inserir um relatório do Power BI, você pode aplicar filtros automaticamente durante a fase de carregamento ou alterar filtros dinamicamente após o relatório ser carregado. Por exemplo, você pode criar seu próprio painel de filtro personalizado e aplicar automaticamente esses filtros a relatórios para mostrar os insights específicos do usuário. Você também pode criar um botão que permite que o usuário aplique filtros ao relatório inserido.

Há suporte para os seguintes tipos de filtro:

• Básico do
• Avançado
• n - ITopNFilter
• data relativa - IRelativeDateFilter
• tempo relativo - IRelativeTimeFilter

Os atributos de objeto de filtro

Todos os tipos de filtro herdam a interface IFilter. Os atributos listados abaixo são relevantes para todos os tipos de filtro.

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

Esquema

O atributo $schema define o tipo de filtro. Há cinco esquemas disponíveis, um para cada tipo de filtro:

• Básico do
• Avançado
• data relativa - https://powerbi.com/product/schema#relativeDate
• tempo relativo - https://powerbi.com/product/schema#relativeTime
• n - https://powerbi.com/product/schema#topN

Configurações de exibição

O atributo displaySettings define a maneira como o filtro é exibido no painel de filtros.

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

• isLockedInViewMode - Um filtro bloqueado é aplicado e exibido no painel de filtro. O valor do filtro não pode ser alterado no modo de exibição . Defina-o como verdadeiro para bloquear o filtro.

• isHiddenInViewMode - Um filtro oculto é aplicado ao relatório, mas não exibido no painel de filtro no modo de exibição . Defina-o como verdadeiro para ocultar o filtro.

• displayName - Um filtro pode ser exibido no painel de filtro com um nome personalizado. Use esse atributo para definir um nome personalizado para o filtro. Quando o valor for indefinido ou nulo, o nome padrão do filtro será exibido (normalmente o nome do campo de dados filtrado).

Tipo de filtro

O atributo filterType define o tipo do filtro. Use a seguinte enumeração, definida na biblioteca de modelos:

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

Alvo

O atributo target define o destino do filtro. Para obter mais informações, consulte Usar destinos para selecionar qual campo de dados agir em.

Atributos adicionais por tipo de filtro

Cada tipo de filtro tem sua própria interface com um conjunto diferente de atributos. As interfaces de filtro fazem parte da biblioteca de powerbi-models.

Filtro básico

de filtro básico tem um único operador com um ou mais valores.

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

• operator - Para filtro básico, o operador pode ser um dos seguintes:

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

• values - Uma matriz de valores para o filtro, todos os valores precisam ser do mesmo tipo.

• requireSingleSelection – define se é possível selecionar vários valores no filtro. Se ele estiver definido como verdadeiro, somente um único valor poderá ser selecionado.

Por exemplo:

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 avançado

de filtro avançado tem um único operador lógico e uma ou duas condições que têm seu próprio operador e valor.

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

• logicalOperator - O operador lógico pode ser um dos seguintes:

  type AdvancedFilterLogicalOperators = "And" | "Or";
  

• conditions - Uma matriz de condições para o filtro avançado, cada condição tem um operator e um value.

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

  Os operadores disponíveis para uma condição são:

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

Por exemplo:

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
}

Nota

Se você estiver criando um AdvancedFilter com apenas uma única condição, defina o logicalOperator como "And". O operador lógico é ignorado ao ser analisado pelo Power BI porque há apenas uma condição e quando o filtro é serializado, o operador lógico padrão é "And". Isso garante que os filtros retornados ao chamar getFilters, correspondam aos definidos usando setFilters.

Filtro N superior

n filtro superior tem um único operador, contador de itens para a quantidade de itens a serem exibidos e pedido por destino.

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

• operator – O operador do filtro N Superior pode ser um dos seguintes:

  type TopNFilterOperators = "Top" | "Bottom";
  

• itemCount - A quantidade de itens a serem exibidos.

• orderBy – o campo de dados de destino pelo qual classificar. Para obter mais informações, consulte Usar destinos para selecionar qual campo de dados agir em.

Por exemplo:

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
};

Filtros relativos de data e hora relativa

O filtro de data relativa e o filtro de tempo relativo herdar da interface IRelativeDateTimeFilter:

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

• operator - O operador para filtros relativos de data e hora pode ser um dos seguintes:

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

• timeUnitsCount - A quantidade de unidades de tempo.

• timeUnitType – define a unidade de tempo que o filtro está usando.

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

  A tabela a seguir lista os horários de unidade com suporte pelos filtros relativos de data e hora relativa.

  Unidade de tempo	Data relativa	Tempo relativo
  Dias	✔	✖
  Semanas	✔	✖
  CalendarWeeks	✔	✖
  Meses	✔	✖
  CalendarMonths	✔	✖
  Anos	✔	✖
  CalendarYears	✔	✖
  Ata	✖	✔
  Horas	✖	✔

• includeToday - Aceita um valor booliano que especifica se o dia atual deve ser incluído no filtro.

  interface IRelativeDateFilter extends IRelativeDateTimeFilter {
  includeToday: boolean;
  }
  

  Nota

  includeToday só é compatível com o filtro de data relativo .

Um exemplo de filtro de data relativo:

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
};

Um exemplo de filtro de tempo 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
};

Filtra APIs

Use os seguintes métodos para obter e atualizar os filtros aplicados a um relatório:

• Obter filtros - getFilters
• de filtros de atualização de .

Obter filtros

Use getFilters para obter todos os filtros de um dos seguintes objetos:

• Relatório
• Página
• Visual

getFilters(): Promise<IFilter[]>

Atualizar filtros

Use updateFilters para adicionar, substituir ou remover filtros no objeto (relatório, página ou visual). Recebe uma operação e uma matriz de filtros opcional.

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

Operação de filtros

Ao chamar updateFilters você precisa passar a operação de filtro deseja pré-formatar. As operações disponíveis são:

• RemoveAll – remove todos os filtros no nível do filtro.
• ReplaceAll – substitui todos os filtros existentes no nível do filtro pelos filtros especificados.
• Add - Adiciona os filtros especificados no nível do filtro (além dos filtros existentes).
• Replace – substitui um filtro existente por um determinado filtro somente se ambos os filtros se aplicarem ao mesmo campo de dados. Se houver um filtro específico que não substitua um filtro existente, ele será adicionado.

Nota

Ao chamar a API com RemoveAll, o argumento de filtros deve ser undefined. Para qualquer outra operação, ela deve ser definida.

Níveis de filtros

A atualização e a obtenção dos filtros podem ser feitas em três níveis. Os filtros em um nível diferente são independentes e a atualização de filtros em um nível não mudará outro. Por exemplo, remover um filtro de página não o remove de outras páginas do relatório.

Os níveis com suporte para filtros são:

• Relatório – os filtros são aplicados a todas as páginas do relatório.
• Página – os filtros são aplicados à página de relatório atual.
• Visual – os filtros são aplicados a um visual específico.

Nota

Somente filtros de nível visual dão suporte ao tipo de filtro ITopNFilter.

Filtros de nível de relatório

Para obter ou atualizar os filtros que se aplicam a todas as páginas do relatório, chame a API relevante no objeto de relatório. Por exemplo:

Obter os filtros de relatório

Obtendo os filtros aplicados a todas as páginas.

let reportFilters = await report.getFilters();

Adicionar novos filtros aos filtros de relatório

Adicionando novos filtros, juntamente com os filtros existentes, para todas as páginas.

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

Remover os filtros de relatório

Remova os filtros aplicados a todas as páginas.

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

Filtros de nível de página

Para obter ou atualizar filtros de nível de página, faça o seguinte:

1. Obtenha o objeto de página da página de destino. Para obter mais informações, consulte Obter páginas e visuais.
2. No objeto de página, chame a API relevante.

Obter os filtros de página

Obtendo os filtros aplicados a uma página específica.

let reportFilters = await page.getFilters();

Substituir todos os filtros de página

Substituindo todos os filtros existentes aplicados a uma página específica, por um novo conjunto de filtros.

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

Remover os filtros de página

Removendo os filtros aplicados a uma página específica.

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

Filtros de nível visual

Para obter ou atualizar filtros de nível visual, faça o seguinte:

1. Obtenha o objeto visual para o visual de destino. Para obter mais informações, consulte Obter páginas e visuais.
2. No objeto visual, chame a API relevante.

Obter os filtros visuais

Obtendo os filtros aplicados a um visual específico.

let reportFilters = await visual.getFilters();

Substituir filtros visuais pelo mesmo destino

Substituindo os filtros de um visual específico. Se existir um filtro com o mesmo campo de dados de destino que um determinado filtro, ele será substituído pelo filtro especificado. Determinados filtros que não correspondem a nenhum filtro existente são adicionados.

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

Remover os filtros visuais

Removendo os filtros aplicados a um visual específico.

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

Considerações e limitações

• Ter mais de duas condições ao criar um filtro Avançado pode causar um comportamento indefinido.

• Não há suporte para tipos de filtro IncludeExclude e Tuple.

• Não há suporte para destinos de tupla e filtro de hierarquia.

Conteúdo relacionado

• Definir configurações de relatório
• segmentações de relatório de controle de
• Personalizar um layout de relatório