Power BI 시각적 개체의 시각적 개체 필터 API

아티클
03/23/2023

시각적 개체 필터 API를 사용하면 Power BI 시각적 개체의 데이터를 필터링할 수 있습니다. 필터 API와 데이터를 선택하는 다른 방법 간의 주요 차이점은 보고서의 다른 시각적 개체에 영향을 주는 방식입니다. 필터가 시각적 개체에 적용되면 다른 시각적 개체에서 강조 표시를 지원해도 필터링된 데이터만 모든 시각적 개체에 표시됩니다.

시각적 개체에 대해 필터링을 사용하려면 capabilities.json 파일의 general 섹션에 filter 개체가 포함되어야 합니다.

"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 추가를 참조하세요. 사용 중인 버전을 확인하려면 pbiviz.json 파일에서 apiVersion을 확인합니다.

모든 필터는 다음 코드에 표시된 대로 IFilter 인터페이스를 사용합니다.

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

여기서 target은 데이터 원본의 테이블 열입니다.

다음과 같은 세 가지 필터 API가 있습니다.

기본 필터 API
고급 필터 API
튜플(다중 열) 필터 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 )

필터를 만들기 위해 powerbi-models의 BasicFilter 클래스를 사용할 수 있습니다.

이전 버전의 도구를 사용하는 경우 다음 코드와 같이 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);

시각적 개체는 생성자 메서드의 시각적 개체에 제공되는 호스트 인터페이스 IVisualHost에서 applyJsonFilter() 메서드를 호출하여 필터를 호출합니다.

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

고급 필터 API

고급 필터 API를 사용하면 LessThan, Contains, Is, IsBlank 등의 여러 조건을 기반으로 하는 복잡한 교차 시각적 개체 데이터 요소 선택 및 필터링 쿼리를 사용할 수 있습니다.

이 필터는 시각적 개체 API 버전 1.7.0에서 도입되었습니다.

‘기본 API’와 반대로 ‘고급 필터 API’에서는 다음과 같습니다.

target에 table과 column 이름이 모두 필요합니다. ‘기본 API’에는 column만 있었습니다.
연산자는 And 및 Or입니다(In 아님).
필터는 인터페이스를 통해 값 대신 조건(less than, greater than 등)을 사용합니다.

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

operator 매개 변수의 조건 연산자는 None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, 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[];
}

Where

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

Important

열 이름 및 조건 값의 순서가 중요합니다.

위의 코드에 해당하는 SQL은 다음과 같습니다.

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

데이터 뷰에서 JSON 필터 복원

API 버전 2.2.0부터, 다음 코드와 같이 VisualUpdateOptions에서 JSON 필터를 복원할 수 있습니다.

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 필터 지우기

필터를 다시 설정하거나 지우려면 필터 API에 null 값을 전달합니다.

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

다음 단계

Power BI 시각적 개체 선택을 사용하여 시각적 개체에 대화형 작업 추가

Share via