Power BI ビジュアルでの Visual Filters APIThe Visual Filters API in Power BI visuals

Visual Filters API を使用すると、Power BI ビジュアルでデータをフィルター処理できます。The Visual Filters API allows you to filter data in Power BI visuals. 他の選択肢との主な違いは、他のビジュアルでの強調表示のサポートに関係なく、他のビジュアルが任意の方法でフィルター処理されることです。The main difference from other selections is that other visuals will be filtered in any way, despite highlight support by other visual.

ビジュアルのフィルター処理を有効にするには、capabilities.json のコードの general セクションに filter オブジェクトが含まれている必要があります。To enable filtering for the visual, it should contain a filter object in the general section of capabilities.json code.

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

Visual Filters API のインターフェイスは、powerbi-models パッケージで使用できます。Visual Filters API interfaces are available in the powerbi-models package. このパッケージには、フィルター インスタンスを作成するためのクラスも含まれています。The package also contains classes to create filter instances.

npm install powerbi-models --save

ツールの古いバージョン (3.x.x より前) を使用する場合は、ビジュアル パッケージに powerbi-models を含める必要があります。If you use an older (earlier than 3.x.x) version of the tools, you should include powerbi-models in the visuals package. 詳細については、簡単なガイド「Advanced Filter API をカスタム ビジュアルに追加する」を参照してください。For more information, see the short guide, Add the Advanced Filter API to the custom visual.

次のコードで示すように、すべてのフィルターでは IFilter インターフェイスが拡張されています。All filters extend the IFilter interface, as shown in the following code:

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

ここで:Where:

  • target は、データ ソースのテーブル列です。target is the table column on the data source.

Basic Filter APIThe Basic Filter API

基本的なフィルターのインターフェイスは次のコードで示すとおりです。Basic filter interface is shown in the following code:

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

ここで:Where:

  • operator は列挙型であり、値は InNotInAll です。operator is an enumeration with the values In, NotIn, and All.
  • values は、条件の値です。values are values for the condition.

基本フィルターの例:Example of a basic filter:

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

このフィルターは、"col1 が値 1、2、または 3 に等しいすべての行を表示する" という意味です。The filter means, "Give me all rows where col1 equals the value 1, 2, or 3."

対応する SQL は次のとおりです。The SQL equivalent is:

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

フィルターを作成するには、powerbi-models の BasicFilter クラスを使用します。To create a filter, you can use the BasicFilter class in powerbi-models.

古いバージョンのツールを使用している場合は、次のコードで示すように、window['powerbi-models'] を使用してウィンドウ オブジェクト内のモデルのインスタンスを取得する必要があります。If you use an older version of the tool, you should get an instance of models in the window object by using window['powerbi-models'], as shown in the following code:

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

ビジュアルでフィルターを呼び出すには、コンストラクターでビジュアルに対して提供されるホスト インターフェイス IVisualHost の applyJsonFilter() メソッドを使用します。The visual invokes the filter by using the applyJsonFilter() method on the host interface, IVisualHost, which is provided to the visual in the constructor.

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

Advanced Filter APIThe Advanced Filter API

Advanced Filter API を使用すると、複数の条件 (LessThanContainsIsIsBlank など) に基づく複雑なクロスビジュアルのデータポイント選択およびフィルター処理のクエリが可能になります。The Advanced Filter API enables complex cross-visual data-point selection and filtering queries that are based on multiple criteria, such as LessThan, Contains, Is, IsBlank, and so on).

このフィルターは、ビジュアル API 1.7.0 で導入されました。The filter was introduced in Visuals API 1.7.0.

Advanced Filter API には、table および column の名前を指定した target も必要です。The Advanced Filter API also requires target with a table and column name. ただし、Advanced Filter API の演算子は AndOr です。But the Advanced Filter API operators are And and Or.

さらに、フィルターでは、インターフェイスでの値ではなく条件が使用されます。Additionally, the filter uses conditions instead of values with the interface:

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

operator パラメーターの条件演算子は、NoneLessThanLessThanOrEqualGreaterThanGreaterThanOrEqualContainsDoesNotContainStartsWithDoesNotStartWithIsIsNotIsBlank、"IsNotBlank" です。Condition operators for the operator parameter are None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank, and "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 は次のとおりです。The SQL equivalent is:

SELECT * FROM table WHERE col1 < 0;

Advanced Filter API の使用に関する完全なサンプル コードについては、Sampleslicer ビジュアル リポジトリを参照してください。For the complete sample code for using the Advanced Filter API, go to the Sampleslicer visual repository.

Tuple Filter API (複数列フィルター)The Tuple Filter API (multi-column filter)

Tuple Filter API は、Visuals API 2.3.0 で導入されました。The Tuple Filter API was introduced in Visuals API 2.3.0. Basic Filter API に似ていますが、複数の列とテーブルに対して条件を定義することができます。It is similar to the Basic Filter API, but it allows you to define conditions for several columns and tables.

そのフィルター インターフェイスは次のコードで示すとおりです。The filter interface is shown in the following code:

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

ここで:Where:

  • target は、テーブル名を持つ列の配列です。target is an array of columns with table names:

    declare type ITupleFilterTarget = IFilterTarget[];
    

    そのフィルターは、さまざまなテーブルの列に対応できます。The filter can address columns from various tables.

  • $schemahttps://powerbi.com/product/schema#tuple です。$schema is https://powerbi.com/product/schema#tuple.

  • filterTypeFilterType.Tuple です。filterType is FilterType.Tuple.

  • operatorIn 演算子でのみ使用できます。operator allows use only in the In operator.

  • values は値のタプルの配列であり、各タプルはターゲット列の値の許可された 1 つの組み合わせを表します。values is an array of value tuples, and each tuple represents one permitted combination of the target column values.

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

完全な例:Complete example:

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

重要

列名と条件値の順序が重要です。The order of the column names and condition values is sensitive.

対応する SQL は次のとおりです。The SQL equivalent is:

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

データ ビューから JSON フィルターを復元するRestore the JSON filter from the data view

API バージョン 2.2.0 以降では、次のコードで示すように、VisualUpdateOptions から JSON フィルターを復元できます。Starting with API version 2.2.0, you can restore the JSON filter from VisualUpdateOptions, as shown in the following code:

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

ブックマークを切り替えると、Power BI によってビジュアルの update メソッドが呼び出されて、ビジュアルは対応する filter オブジェクトを取得します。When you switch, bookmarks, Power BI calls the update method of the visual, and the visual gets a corresponding filter object. 詳細については、「Power BI ビジュアルのブックマーク サポートを追加する」を参照してください。For more information, see Add bookmark support for Power BI visuals.

JSON フィルターのサンプルSample JSON filter

次の図では、JSON フィルターのコードのサンプルをいくつか示します。Some sample JSON filter code is shown in the following image:

JSON フィルターのコード

JSON フィルターをクリアするClear the JSON filter

Filter API では、フィルターの null 値を reset または clear として受け入れます。The Filter API accepts the null value of the filter as reset or clear.

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