レポートフィルターを制御する

[アーティクル]
07/09/2024

Power BI レポートを埋め込む場合は、読み込みフェーズ中フィルターを自動的に適用したり、レポートの読み込み後にフィルターを動的に変更したりできます。たとえば、独自のカスタムフィルターウィンドウを作成し、それらのフィルターをレポートに自動的に適用して、ユーザー固有の分析情報を表示できます。ユーザーが埋め込みレポートにフィルターを適用できるようにするボタンを作成することもできます。

次のフィルターの種類がサポートされています。

Basic - IBasicFilter
Advanced - IAdvancedFilter
トップ N - ITopNFilter
相対日付 - IRelativeDateFilter
相対時間 - IRelativeTimeFilter

フィルターオブジェクトの属性

すべてのフィルターの種類は、IFilter インターフェイスを継承します。以下に示す属性は、すべてのフィルターの種類に関連します。

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

スキーマ

$schema 属性は、フィルターの種類を定義します。フィルターの種類ごとに 1 つずつ、5 つのスキーマを使用できます。

Basic - https://powerbi.com/product/schema#basic
Advanced - https://powerbi.com/product/schema#advanced
相対日付 - https://powerbi.com/product/schema#relativeDate
相対時間 - https://powerbi.com/product/schema#relativeTime
トップ N - https://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 ライブラリの一部です。

基本フィルター

基本フィルターには、1 つ以上の値を持つ 1 つの演算子があります。

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

operator - 基本フィルターの場合、演算子は次のいずれかになります。
```
type BasicFilterOperators = "In" | "NotIn" | "All"
```
values - フィルターの値の配列。すべての値が同じ型である必要があります。
requireSingleSelection - フィルターで複数の値を選択できるかどうかを定義します。 true設定されている場合は、1 つの値のみを選択できます。

例えば：

const basicFilter = {
  $schema: "https://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter,
  requireSingleSelection: true
}

高度なフィルター

高度なフィルターには、1 つの論理演算子と、独自の演算子と値を持つ 1 つまたは 2 つの条件があります。

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: "https://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
}

手記

条件が 1 つだけの AdvancedFilter を作成する場合は、logicalOperator を "And"に設定します。論理演算子は、条件が 1 つしかないため Power BI によって解析される場合は無視され、フィルターをシリアル化すると、既定の論理演算子が "And"されます。これにより、getFiltersを呼び出すときに返されるフィルターが、setFiltersを使用して設定されたものと一致します。

上位 N 個のフィルター

top N フィルターには、1 つの演算子、表示する項目の量の項目カウンター、およびターゲット別の注文があります。

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

operator - Top N フィルターの演算子は、次のいずれかになります。
```
type TopNFilterOperators = "Top" | "Bottom";
```
itemCount - 表示する項目の量。
orderBy - 並べ替えの基準となるターゲットデータフィールド。詳細については、「ターゲットを使用して、で動作するデータフィールドを選択する」を参照してください。

例えば：

const topNFilter = {
  $schema: "https://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: "https://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: "https://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>>

フィルター操作

を呼び出すときは、プリフォームフィルター操作を渡す必要があります。使用可能な操作は次のとおりです。

RemoveAll - フィルターレベルのすべてのフィルターを削除します。
ReplaceAll - フィルターレベルのすべての既存のフィルターを特定のフィルターに置き換えます。
Add - (既存のフィルターに加えて) 特定のフィルターをフィルターレベルに追加します。
Replace - 両方のフィルターが同じデータフィールドに適用される場合にのみ、既存のフィルターを特定のフィルターに置き換えます。既存のフィルターを置き換えない特定のフィルターがある場合は、追加されます。

手記

RemoveAllを使用して API を呼び出す場合は、フィルター引数を undefinedする必要があります。その他の操作の場合は、定義する必要があります。

フィルターレベル

フィルターの更新と取得は、3 つのレベルで実行できます。異なるレベルのフィルターは独立しており、あるレベルでフィルターを更新すると、別のレベルは変更されません。たとえば、ページフィルターを削除しても、レポート内の他のページからは削除されません。

フィルターでサポートされているレベルは次のとおりです。

レポート - フィルターはレポート内のすべてのページに適用されます。
ページ - フィルターは現在のレポートページに適用されます。
ビジュアル - フィルターは特定のビジュアルに適用されます。

手記

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

考慮事項と制限事項

高度なフィルターを構築するときに 2 つ以上の条件があると、未定義の動作が発生する可能性があります。
IncludeExclude フィルターと Tuple フィルターの種類はサポートされていません。
タプルと階層のフィルターターゲットはサポートされていません。

次の方法で共有

レポートフィルターを制御する

フィルターオブジェクトの属性

スキーマ

表示設定

フィルターの種類

ターゲット

フィルターの種類別の追加属性

基本フィルター

高度なフィルター

上位 N 個のフィルター

相対日付フィルターと相対時間フィルター

フィルター API

フィルターを取得する

フィルターの更新

フィルター操作

フィルターレベル

レポートレベルフィルター

レポートフィルターを取得する

レポートフィルターに新しいフィルターを追加する

レポートフィルターを削除する

ページレベルフィルター

ページフィルターを取得する

すべてのページフィルターを置き換える

ページフィルターを削除する

ビジュアルレベルフィルター

ビジュアルフィルターを取得する

ビジュアルフィルターを同じターゲットに置き換える

ビジュアルフィルターを削除する

考慮事項と制限事項

その他のリソース

次の方法で共有

レポート フィルターを制御する

フィルター オブジェクトの属性

スキーマ

表示設定

フィルターの種類

ターゲット

フィルターの種類別の追加属性

基本フィルター

高度なフィルター

上位 N 個のフィルター

相対日付フィルターと相対時間フィルター

フィルター API

フィルターを取得する

フィルターの更新

フィルター操作

フィルター レベル

レポート レベル フィルター

レポート フィルターを取得する

レポート フィルターに新しいフィルターを追加する

レポート フィルターを削除する

ページ レベル フィルター

ページ フィルターを取得する

すべてのページ フィルターを置き換える

ページ フィルターを削除する

ビジュアル レベル フィルター

ビジュアル フィルターを取得する

ビジュアル フィルターを同じターゲットに置き換える

ビジュアル フィルターを削除する

考慮事項と制限事項

関連コンテンツ

その他のリソース

レポートフィルターを制御する

フィルターオブジェクトの属性

フィルターレベル

レポートレベルフィルター

レポートフィルターを取得する

レポートフィルターに新しいフィルターを追加する

レポートフィルターを削除する

ページレベルフィルター

ページフィルターを取得する

すべてのページフィルターを置き換える

ページフィルターを削除する

ビジュアルレベルフィルター

ビジュアルフィルターを取得する

ビジュアルフィルターを同じターゲットに置き換える

ビジュアルフィルターを削除する