API визуальных фильтров в визуальных элементах Power BI

  • Статья

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

Чтобы включить фильтрацию для визуального элемента, файл capabilities.json должен содержать filter объект в general разделе.

"objects": {
        "general": {
            "displayName": "General",
            "displayNameKey": "formattingGeneral",
            "properties": {
                "filter": {
                    "type": {
                        "filter": true
                    }
                }
            }
        }
    }

Примечание.

  • Интерфейсы API визуальных фильтров доступны в пакете powerbi-models . Этот пакет также содержит классы для создания экземпляров фильтра.

    npm install powerbi-models --save

  • Если вы используете более раннюю версию средств (более раннюю версию 3.x.x), включите powerbi-models в пакет визуальных элементов. Дополнительные сведения см. в кратком руководстве по добавлению API расширенного фильтра в пользовательский визуальный элемент. Чтобы узнать, какая версия используется, проверка apiVersion в файле pbiviz.json.

Все фильтры используют IFilter интерфейс, как показано в следующем коде:

export interface IFilter {
        $schema: string;
        target: IFilterTarget;
}

Где target находится столбец таблицы в источнике данных.

Существует три API фильтра:

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

Базовый интерфейс фильтра показан в следующем коде:

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

Где:

  • operator — это перечисление со значениями In, NotIn и All.
  • values — это значения условия.

Пример базового фильтра

В следующем примере возвращаются все строки, в которых col1 равно значение 1, 2 или 3.

let basicFilter = {
    target: {
        column: "Col1"
    },
    operator: "In",
    values: [1,2,3]
}

Эквивалент SQL из приведенного выше примера:

SELECT * FROM table WHERE col1 IN ( 1 , 2 , 3 )

Чтобы создать фильтр, можно использовать класс BasicFilter в powerbi-models.

При использовании более старой версии средства необходимо получить экземпляр моделей в объекте окна, window['powerbi-models']как показано в следующем коде:

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')),
    column: categories.source.displayName
};

let values = [ 1, 2, 3 ];

let filter: IBasicFilter = new window['powerbi-models'].BasicFilter(target, "In", values);

Визуальный элемент вызывает фильтр, вызывая applyJsonFilter() метод в интерфейсе узла, IVisualHostкоторый предоставляется визуальному элементу в методе конструктора.

IVisualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

API расширенного фильтра

API расширенного фильтра позволяет выполнять сложные кросс-визуальные запросы на выбор и фильтрацию запросов, основанных на нескольких критериях, таких как LessThan, Contains, IsBlank и т. д.).

Этот фильтр появился в API Visuals версии 1.7.0.

В отличие от API Уровня "Базовый", в API расширенного фильтра:

  • Требуется target как имяtable, так и column имя (только что был columnAPI "Базовый").
  • Операторы : And and Or (в отличие от In).
  • Фильтр использует условия (меньше, больше и т. д.) вместо значений с интерфейсом:
interface IAdvancedFilterCondition {
    value: (string | number | boolean);
    operator: AdvancedFilterConditionOperators;
}

Операторы условий operator для параметра: None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain,StartWith, DoesNotStartWith, IsNot, IsBlank и IsNotBlank'

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')), // table
    column: categories.source.displayName // col1
};

let conditions: IAdvancedFilterCondition[] = [];

conditions.push({
    operator: "LessThan",
    value: 0
});

let filter: IAdvancedFilter = new window['powerbi-models'].AdvancedFilter(target, "And", conditions);

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Эквивалент SQL:

SELECT * FROM table WHERE col1 < 0;

Полный пример кода для использования API расширенного фильтра перейдите в визуальный репозиторий Sampleslicer.

API фильтра кортежей (фильтр с несколькими столбцами)

API фильтра кортежей появился в API визуальных элементов 2.3.0. Он похож на API базовых фильтров, но позволяет определить условия для нескольких столбцов и таблиц.

Интерфейс фильтра показан в следующем коде:

interface ITupleFilter extends IFilter {
    $schema: string;
    filterType: FilterType;
    operator: TupleFilterOperators;
    target: ITupleFilterTarget;
    values: TupleValueType[];
}

Где

  • target — это массив столбцов с именами таблиц:

    declare type ITupleFilterTarget = IFilterTarget[];

    Фильтр может обращаться к столбцам из различных таблиц.

  • $schema имеет значение https://powerbi.com/product/schema#tuple.

  • filterType — FilterType.Tuple.

  • operator разрешает использовать только в операторе In .

  • values — это массив кортежей значений. Каждый кортеж представляет одну разрешенную комбинацию значений целевого столбца.

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

Полный пример:

let target: ITupleFilterTarget = [
    {
        table: "DataTable",
        column: "Team"
    },
    {
        table: "DataTable",
        column: "Value"
    }
];

let values = [
    [
        // the first column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team1" // the value for the `Team` column of the `DataTable` table
        },
        {
            value: 5 // the value for the `Value` column of the `DataTable` table
        }
    ],
    [
        // the second column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team2" // the value for `Team` column of `DataTable` table
        },
        {
            value: 6 // the value for `Value` column of `DataTable` table
        }
    ]
];

let filter: ITupleFilter = {
    $schema: "https://powerbi.com/product/schema#tuple",
    filterType: FilterType.Tuple,
    operator: "In",
    target: target,
    values: values
}

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Важно!

Порядок имен столбцов и значений условий важен.

Эквивалент SQL приведенного выше кода:

SELECT * FROM DataTable WHERE ( Team = "Team1" AND Value = 5 ) OR ( Team = "Team2" AND Value = 6 );

Восстановление фильтра JSON из представления данных

Начиная с API версии 2.2.0 можно восстановить фильтр JSON из VisualUpdateOptions, как показано в следующем коде:

export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
    viewport: IViewport;
    dataViews: DataView[];
    type: VisualUpdateType;
    viewMode?: ViewMode;
    editMode?: EditMode;
    operationKind?: VisualDataChangeOperationKind;
    jsonFilters?: IFilter[];
}

При переключении закладок Power BI вызывает update метод визуального элемента, а визуальный элемент получает соответствующий filter объект. Дополнительные сведения см. в разделе "Добавление поддержки закладок для визуальных элементов Power BI".

Пример фильтра JSON

Пример кода фильтра JSON показан на следующем рисунке:

Screenshot of sample JSON filter code showing values in an array.

Очистка фильтра JSON

Чтобы сбросить или очистить фильтр, передайте null значение в API фильтра.

// invoke the filter
visualHost.applyJsonFilter(null, "general", "filter", FilterAction.merge);

Связанный контент

Использование выбора визуальных элементов Power BI для добавления интерактивности в визуальный элемент