Управление фильтрами отчетов

Статья
07/09/2024

При внедрении отчета Power BI можно применять фильтры автоматически во время загрузки или динамически изменять фильтры после загрузки отчета. Например, вы можете создать собственную настраиваемую панель фильтров и автоматически применить эти фильтры к отчетам, чтобы показать пользовательский аналитический сведения. Вы также можете создать кнопку, которая позволяет пользователю применять фильтры к внедренным отчетам.

Поддерживаются следующие типы фильтров:

базовый - IBasicFilter
Расширенные - IAdvancedFilter
top N - ITopNFilter
относительная дата - IRelativeDateFilter
относительное время - IRelativeTimeFilter

Атрибуты объекта фильтра

Все типы фильтров наследуют интерфейс IFilter. Перечисленные ниже атрибуты относятся ко всем типам фильтров.

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

Схема

Атрибут $schema определяет тип фильтра. Существует пять схем, по одному для каждого типа фильтра:

базовый - https://powerbi.com/product/schema#basic
Расширенные - https://powerbi.com/product/schema#advanced
относительная дата - https://powerbi.com/product/schema#relativeDate
относительное время - https://powerbi.com/product/schema#relativeTime
top N - https://powerbi.com/product/schema#topN

Параметры отображения

Атрибут displaySettings определяет способ отображения фильтра в области фильтров.

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

isLockedInViewMode . Заблокированный фильтр применяется и отображается в области фильтров. Значение фильтра нельзя изменить в режиме просмотра . Задайте для него значение true, чтобы заблокировать фильтр.
isHiddenInViewMode . Скрытый фильтр применяется к отчету, но не отображается в области фильтров в режиме режиме просмотра. Задайте для него значение true, чтобы скрыть фильтр.
displayName . Фильтр можно отобразить в области фильтров с персонализированным именем. Используйте этот атрибут, чтобы задать персонализированное имя фильтра. Если значение не определено или равно null, будет отображаться имя фильтра по умолчанию (обычно имя отфильтрованного поля данных).

Тип фильтра

Атрибут filterType определяет тип фильтра. Используйте следующую перечисление, определенную в библиотеке моделей:

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

Цель

Атрибут target определяет целевой объект фильтра. Дополнительные сведения см. в разделе Использование целевых объектов для выбора поля данных для.

Дополнительные атрибуты по типу фильтра

Каждый тип фильтра имеет собственный интерфейс с различным набором атрибутов. Интерфейсы фильтров являются частью библиотеки powerbi-models.

Базовый фильтр

базовый фильтр имеет один оператор с одним или несколькими значениями.

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

operator. Для базового фильтра оператор может быть одним из следующих вариантов:
```
type BasicFilterOperators = "In" | "NotIn" | "All"
```
values — массив значений фильтра, все значения должны иметь одинаковый тип.
requireSingleSelection. Определяет, можно ли выбрать несколько значений в фильтре. Если задано значение true true, можно выбрать только одно значение.

Например:

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
}

Расширенный фильтр

расширенный фильтр имеет один логический оператор и одно или два условия, имеющие собственный оператор и значение.

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

logicalOperator. Логический оператор может быть одним из следующих:
```
type AdvancedFilterLogicalOperators = "And" | "Or";
```

conditions — массив условий для расширенного фильтра, каждое условие имеет operator и value.

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

Доступные операторы для условия:

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

Например:

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
}

Заметка

Если вы создаете AdvancedFilter только с одним условием, задайте для logicalOperator значение "And". Логический оператор игнорируется при анализе Power BI, так как существует только одно условие, а при сериализации фильтра логический оператор по умолчанию "And". Это гарантирует, что фильтры, возвращаемые при вызове getFilters, соответствуют заданным значениям с помощью setFilters.

Верхний N-фильтр

фильтр top N имеет один оператор, счетчик элементов для количества отображаемых элементов и порядка по целевому объекту.

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

operator . Оператор для фильтра Top N может быть одним из следующих:
```
type TopNFilterOperators = "Top" | "Bottom";
```
itemCount — количество отображаемых элементов.
orderBy — целевое поле данных для сортировки по. Дополнительные сведения см. в разделе Использование целевых объектов для выбора поля данных для.

Например:

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

Относительные фильтры даты и времени

Фильтр относительной даты и относительный фильтр времени наследуется от интерфейса IRelativeDateTimeFilter:

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

operator . Оператор для относительных фильтров даты и времени может быть одним из следующих:
```
enum RelativeDateOperators {
    InLast = 0,
    InThis = 1,
    InNext = 2,
}
```
timeUnitsCount — количество единиц времени.

timeUnitType— определяет единицу времени использования фильтра.

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

В следующей таблице перечислены единицы времени, поддерживаемые относительными фильтрами даты и относительного времени.

Единица времени	Относительная дата	Относительное время
Дни недели	✔	✖
Недель	✔	✖
CalendarWeeks	✔	✖
Месяцы	✔	✖
CalendarMonths	✔	✖
Годы	✔	✖
CalendarYears	✔	✖
Протокол	✖	✔
Часов	✖	✔

includeToday — принимает логическое значение, указывающее, следует ли включать текущий день в фильтр.
```
interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}
```
Заметка

поддерживается только фильтром относительной даты.

Пример фильтра относительных дат:

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

Пример относительного фильтра времени:

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

Чтобы получить и обновить фильтры, примененные к отчету, используйте следующие методы:

получение фильтров - getFilters
фильтры обновлений- updateFilters.

Получение фильтров

Используйте getFilters, чтобы получить все фильтры для одного из следующих объектов:

Сообщать
Страница
Зрительный

getFilters(): Promise<IFilter[]>

Обновление фильтров

Используйте updateFilters для добавления, замены или удаления фильтров в объекте (отчет, страница или визуальный элемент). Получает операцию и необязательный массив фильтров.

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

Операция фильтров

При вызове updateFilters необходимо передать операцию фильтрации , которую требуется преформировать. Доступные операции:

RemoveAll. Удаляет все фильтры на уровне фильтра.
ReplaceAll. Заменяет все существующие фильтры на уровне фильтра указанными фильтрами.
Add. Добавляет указанные фильтры на уровне фильтра (помимо существующих фильтров).
Replace. Заменяет существующий фильтр заданным фильтром только в том случае, если оба фильтра применяются к одному полю данных. Если существует заданный фильтр, который не заменяет существующий фильтр, он будет добавлен.

Заметка

При вызове API с RemoveAllаргумент фильтров должен быть undefined. Для любых других операций он должен быть определен.

Уровни фильтров

Обновление и получение фильтров можно выполнить на трех уровнях. Фильтры на разных уровнях независимы, а обновление фильтров на одном уровне не изменится. Например, удаление фильтра страниц не удаляет его из других страниц отчета.

Поддерживаемые уровни для фильтров:

отчета. Фильтры применяются ко всем страницам отчета.
страница . Фильтры применяются к текущей странице отчета.
visual . Фильтры применяются к конкретному визуальному элементу.

Заметка

Только фильтры визуального уровня поддерживают тип фильтра ITopNFilter.

Фильтры уровня отчета

Чтобы получить или обновить фильтры, применяемые ко всем страницам отчета, вызовите соответствующий API для объекта отчета. Например:

Получение фильтров отчета

Получение фильтров, применяемых ко всем страницам.

let reportFilters = await report.getFilters();

Добавление новых фильтров в фильтры отчета

Добавление новых фильтров вместе с существующими фильтрами для всех страниц.

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

Удаление фильтров отчетов

Удалите фильтры, примененные ко всем страницам.

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

Фильтры уровня страницы

Чтобы получить или обновить фильтры уровня страницы, сделайте следующее:

Получите объект страницы для целевой страницы. Дополнительные сведения см. в разделе Получение страниц и визуальных элементов.
На объекте страницы вызовите соответствующий API.

Получение фильтров страниц

Получение фильтров, примененных к определенной странице.

let reportFilters = await page.getFilters();

Замена всех фильтров страниц

Замена всех существующих фильтров, примененных к определенной странице, новым набором фильтров.

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

Удаление фильтров страниц

Удаление фильтров, примененных к определенной странице.

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

Фильтры визуального уровня

Чтобы получить или обновить фильтры визуального уровня, сделайте следующее:

Получите визуальный объект для целевого визуального элемента. Дополнительные сведения см. в разделе Получение страниц и визуальных элементов.
В визуальном объекте вызовите соответствующий API.

Получение визуальных фильтров

Получение фильтров, примененных к определенному визуальному элементу.

let reportFilters = await visual.getFilters();

Замена визуальных фильтров тем же целевым объектом

Замена фильтров определенного визуального элемента. Если фильтр существует с тем же целевым полем данных, что и заданный фильтр, он заменяется заданным фильтром. При добавлении фильтров, которые не соответствуют существующему фильтру.

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

Удаление визуальных фильтров

Удаление фильтров, примененных к определенному визуальному элементу.

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

Поделиться через

Управление фильтрами отчетов

Атрибуты объекта фильтра

Схема

Параметры отображения

Тип фильтра

Цель

Дополнительные атрибуты по типу фильтра

Базовый фильтр

Расширенный фильтр

Верхний N-фильтр

Относительные фильтры даты и времени

Фильтры API

Получение фильтров

Обновление фильтров

Операция фильтров

Уровни фильтров

Фильтры уровня отчета

Получение фильтров отчета

Добавление новых фильтров в фильтры отчета

Удаление фильтров отчетов

Фильтры уровня страницы

Получение фильтров страниц

Замена всех фильтров страниц

Удаление фильтров страниц

Фильтры визуального уровня

Получение визуальных фильтров

Замена визуальных фильтров тем же целевым объектом

Удаление визуальных фильтров

Рекомендации и ограничения

Дополнительные ресурсы

Поделиться через

Управление фильтрами отчетов

Атрибуты объекта фильтра

Схема

Параметры отображения

Тип фильтра

Цель

Дополнительные атрибуты по типу фильтра

Базовый фильтр

Расширенный фильтр

Верхний N-фильтр

Относительные фильтры даты и времени

Фильтры API

Получение фильтров

Обновление фильтров

Операция фильтров

Уровни фильтров

Фильтры уровня отчета

Получение фильтров отчета

Добавление новых фильтров в фильтры отчета

Удаление фильтров отчетов

Фильтры уровня страницы

Получение фильтров страниц

Замена всех фильтров страниц

Удаление фильтров страниц

Фильтры визуального уровня

Получение визуальных фильтров

Замена визуальных фильтров тем же целевым объектом

Удаление визуальных фильтров

Рекомендации и ограничения

Связанное содержимое

Дополнительные ресурсы