Controlar filtros de relatório

  • Artigo

Ao inserir um relatório do Power BI, você pode aplicar filtros automaticamente durante a fase de carregamento ou alterar filtros dinamicamente depois que o relatório é 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:

Os atributos de objeto de filtro

Todos os tipos de filtro herdam a IFilter interface. 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 $schema atributo define o tipo de filtro. Há cinco esquemas disponíveis, um para cada tipo de filtro:

  • Basic - http://powerbi.com/product/schema#basic
  • Avançado - http://powerbi.com/product/schema#advanced
  • Data relativa - http://powerbi.com/product/schema#relativeDate
  • Tempo relativo - http://powerbi.com/product/schema#relativeTime
  • N Superior - http://powerbi.com/product/schema#topN

Configurações de vídeo

O displaySettings atributo define a forma 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 true 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 true 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 filterType atributo 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,
}

Destino

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

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 modelos powerbi .

Filtro básico

O 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 for definido como true, somente um único valor poderá ser selecionado.

Por exemplo:

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

O 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: "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
}

Observação

Se você estiver criando um AdvancedFilter com apenas uma única condição, defina como "And"logicalOperator . 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

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

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

  • operator - O operador do filtro Top N 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 em qual campo de dados agir.

Por exemplo:

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

Filtros relativos de data e hora relativa

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

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 ✔ ✖
    Months ✔ ✖
    CalendarMonths ✔ ✖
    Years ✔ ✖
    CalendarYears ✔ ✖
    minutos ✖ ✔
    Horas ✖ ✔

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

    interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}

    Observação

    includeToday só há suporte para o filtro de data relativo.

Um exemplo de filtro de data relativa:

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

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

Filtra APIs

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

Obter filtros

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

  • Relatório
  • ?
  • 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 Filters

Ao chamar updateFilters , você precisa passar na operação de filtro que 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 determinados.
  • Add - Adiciona os filtros determinados 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 determinado filtro que não substitua um filtro existente, ele será adicionado.

Observação

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

Atualizar e obter os filtros pode ser feito em três níveis. Os filtros em diferentes níveis são independentes e a atualização de filtros em um nível não alterará outro. Por exemplo, remover um filtro de página não o remove de outras páginas no 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.

Observação

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

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, confira 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, confira 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);

Limitações

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

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

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

Próximas etapas