보고서 필터 제어

아티클
06/24/2024

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

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

기본 - IBasicFilter
고급 - IAdvancedFilter
상위 N
상대 날짜 - 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

표시 설정

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 및 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"설정합니다. 하나의 조건만 있고 필터가 serialize될 때 기본 논리 연산자는 "And"때문에 Power BI에서 구문 분석할 때 논리 연산자는 무시됩니다. 이렇게 하면 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: "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

보고서에 적용된 필터를 가져와 업데이트하려면 다음 방법을 사용합니다.

필터 가져오기
- updateFilters필터를 업데이트합니다.

필터 가져오기

getFilters 사용하여 다음 개체 중 하나에 대한 모든 필터를 가져옵니다.

보고서
페이지
시각의

getFilters(): Promise<IFilter[]>

필터 업데이트

updateFilters 사용하여 개체(보고서, 페이지 또는 시각적 개체)에서 필터를 추가, 바꾸기 또는 제거합니다. 작업 및 선택적 필터 배열을 받습니다.

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

필터 작업

updateFilters 호출할 때는 프리포밍하려는 필터 작업을 전달해야 합니다. 사용 가능한 작업은 다음과 같습니다.

RemoveAll - 필터 수준에서 모든 필터를 제거합니다.
ReplaceAll - 필터 수준의 모든 기존 필터를 지정된 필터로 바꿉니다.
Add - 필터 수준(기존 필터 외에)에 지정된 필터를 추가합니다.
Replace - 두 필터가 동일한 데이터 필드에 적용되는 경우에만 기존 필터를 지정된 필터로 바꿉니다. 기존 필터를 대체하지 않는 지정된 필터가 있는 경우 추가됩니다.

메모

RemoveAll사용하여 API를 호출할 때 필터 인수는 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);

제한

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

다음 단계

보고서 설정 구성
보고서 슬라이서 제어
보고서 레이아웃 개인 설정

다음을 통해 공유

보고서 필터 제어

필터 개체 특성

스키마

표시 설정

필터 형식

과녁

필터 유형별 추가 특성

기본 필터

고급 필터

상위 N개 필터

상대 날짜 및 상대 시간 필터

필터 API

필터 가져오기

필터 업데이트

필터 작업

필터 수준

보고서 수준 필터

보고서 필터 가져오기

보고서 필터에 새 필터 추가

보고서 필터 제거

페이지 수준 필터

페이지 필터 가져오기

모든 페이지 필터 바꾸기

페이지 필터 제거

시각적 수준 필터

시각적 필터 가져오기

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

시각적 개체 필터 제거

제한

다음 단계

추가 리소스