보고서 필터 제어

아티클
09/17/2023

Power BI 보고서를 포함하는 경우 로드 단계 중에 필터를 자동으로 적용하거나 보고서가 로드된 후 필터를 동적으로 변경할 수 있습니다. 예를 들어 사용자 고유의 사용자 지정 필터 창을 만들고 해당 필터를 보고서에 자동으로 적용하여 사용자별 인사이트를 표시할 수 있습니다. 사용자가 포함된 보고서에 필터를 적용할 수 있는 단추를 만들 수도 있습니다.

지원되는 필터 형식은 다음과 같습니다.

기본 - IBasicFilter
고급 - IAdvancedFilter
상위 N - ITopNFilter
상대 날짜 - IRelativeDateFilter
상대 시간 - IRelativeTimeFilter

필터 개체 특성

모든 필터 형식은 인터페이스를 상속합니다 IFilter . 아래에 나열된 특성은 모든 필터 형식과 관련이 있습니다.

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

스키마

이 특성은 $schema 필터 유형을 정의합니다. 각 필터 유형에 대해 하나씩 5개의 스키마를 사용할 수 있습니다.

기본 - http://powerbi.com/product/schema#basic
고급 - http://powerbi.com/product/schema#advanced
상대 날짜 - http://powerbi.com/product/schema#relativeDate
상대 시간 - http://powerbi.com/product/schema#relativeTime
상위 N - http://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로 설정된 경우 단일 값만 선택할 수 있습니다.

예를 들면 다음과 같습니다.

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
}

고급 필터

고급 필터 에는 단일 논리 연산자와 고유한 연산자와 값이 있는 하나 또는 두 개의 조건이 있습니다.

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

logicalOperator - 논리 연산자는 다음 중 하나일 수 있습니다.
```
type AdvancedFilterLogicalOperators = "And" | "Or";
```

conditions - 고급 필터에 대한 조건의 배열이며, 각 조건에는 operator 1과 1이 있습니다 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: "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
}

참고

단일 조건만 사용하여 AdvancedFilter 만드는 경우 다음으로 설정합니다 logicalOperator"And". 하나의 조건만 있고 필터가 직렬화될 때 기본 논리 연산자는 Power BI에서 구문 분석할 때 논리 연산자가 무시됩니다 "And". 이렇게 하면 호출 getFilters할 때 반환되는 필터가 .를 사용하여 setFilters설정된 필터와 일치합니다.

상위 N 필터

상위 N 필터 에는 단일 연산자, 표시할 항목의 양에 대한 항목 카운터 및 대상별 순서가 있습니다.

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

operator - Top N 필터의 연산자는 다음 중 하나일 수 있습니다.
```
type TopNFilterOperators = "Top" | "Bottom";
```
itemCount - 표시할 항목의 양입니다.
orderBy - 정렬할 대상 데이터 필드입니다. 자세한 내용은 대상을 사용하여 수행할 데이터 필드를 선택합니다.

예를 들면 다음과 같습니다.

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

상대 날짜 및 상대 시간 필터

상대 날짜 필터와 상대 시간 필터는 모두 인터페이스에서 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;
}
```
참고

includeToday 는 상대 날짜 필터에서만 지원됩니다.

상대 날짜 필터 예제:

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

상대 시간 필터 예제:

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

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합니다. 다른 작업의 경우 정의해야 합니다.

필터 수준

필터 업데이트 및 가져오기는 세 가지 수준에서 수행할 수 있습니다. 다른 수준의 필터는 독립적이며 한 수준에서 필터를 업데이트해도 다른 필터는 변경되지 않습니다. 예를 들어 페이지 필터를 제거해도 보고서의 다른 페이지에서는 제거되지 않습니다.

필터에 지원되는 수준은 다음과 같습니다.

보고서 - 필터가 보고서의 모든 페이지에 적용됩니다.
페이지 - 필터가 현재 보고서 페이지에 적용됩니다.
시각적 개체 - 필터가 특정 시각적 개체에 적용됩니다.

참고

시각적 수준 필터만 필터 유형을 지원 ITopNFilter 합니다.

보고서 수준 필터

보고서의 모든 페이지에 적용되는 필터를 다운로드하거나 업데이트하려면 보고서 개체의 관련 API를 호출합니다. 예를 들면 다음과 같습니다.

보고서 필터 가져오기

모든 페이지에 적용된 필터 가져오기

let reportFilters = await report.getFilters();

보고서 필터에 새 필터 추가

모든 페이지에 대해 기존 필터와 함께 새 필터를 추가합니다.

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

보고서 필터 제거

모든 페이지에 적용된 필터를 제거합니다.

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

페이지 수준 필터

페이지 수준 필터를 다운로드하거나 업데이트하려면 다음을 수행합니다.

대상 페이지의 페이지 개체를 가져옵니다. 자세한 내용은 Get pages and visuals(페이지 및 시각적 개체 가져오기)를 참조하세요.
페이지 개체에서 관련 API를 호출합니다.

페이지 필터 가져오기

특정 페이지에 적용된 필터 가져오기

let reportFilters = await page.getFilters();

모든 페이지 필터 바꾸기

특정 페이지에 적용된 모든 기존 필터를 새 필터 집합으로 바꿔야 합니다.

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

페이지 필터 제거

특정 페이지에 적용된 필터를 제거합니다.

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

시각적 개체 수준 필터

시각적 수준 필터를 다운로드하거나 업데이트하려면 다음을 수행합니다.

대상 시각적 개체의 시각적 개체를 가져옵니다. 자세한 내용은 Get pages and visuals(페이지 및 시각적 개체 가져오기)를 참조하세요.
시각적 개체에서 관련 API를 호출합니다.

시각적 개체 필터 가져오기

특정 시각적 개체에 적용된 필터 가져오기

let reportFilters = await visual.getFilters();

시각적 필터를 동일한 대상으로 바꾸기

특정 시각적 개체의 필터 바꾸기 지정된 필터와 동일한 대상 데이터 필드가 있는 필터가 있는 경우 지정된 필터로 바뀝니다. 기존 필터와 일치하지 않는 지정된 필터가 추가됩니다.

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

시각적 개체 필터 제거

특정 시각적 개체에 적용된 필터 제거

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

제한 사항

고급 필터를 빌드할 때 두 개 이상의 조건이 있으면 정의되지 않은 동작이 발생할 수 있습니다.
IncludeExclude 및 Tuple 필터 형식은 지원되지 않습니다.
튜플 및 계층 필터 대상은 지원되지 않습니다.

보고서 필터 제어

필터 개체 특성

스키마

디스플레이 설정

필터 형식

대상

필터 형식별 추가 특성

기본 필터

고급 필터

상위 N 필터

상대 날짜 및 상대 시간 필터

API 필터링

필터 가져오기

필터 업데이트

필터 작업

필터 수준

보고서 수준 필터

보고서 필터 가져오기

보고서 필터에 새 필터 추가

보고서 필터 제거

페이지 수준 필터

페이지 필터 가져오기

모든 페이지 필터 바꾸기

페이지 필터 제거

시각적 개체 수준 필터

시각적 개체 필터 가져오기

시각적 필터를 동일한 대상으로 바꾸기

시각적 개체 필터 제거

제한 사항

다음 단계

추가 리소스