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

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

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

• 基本的な - IBasicFilter
• 詳細 - IAdvancedFilter
• 上位 N - ITopNFilter
• 相対日付 - IRelativeDateFilter
• 相対時間 - IRelativeTimeFilter

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

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

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

スキーマ

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

• 基本的な - 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 ライブラリの一部です。

基本フィルター

基本フィルター には、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: "http://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 - 高度なフィルターの条件の配列で、各条件には 1 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
}

Note

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

上位 N のフィルター

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

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	✔	✖
  Months	✔	✖
  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 します。

• レポート
• ページ
• Visual

getFilters(): Promise<IFilter[]>

フィルターの更新

オブジェクト (レポート、ページ、ビジュアル) のフィルターを追加、置換、または削除するために使用 updateFilters します。 操作とオプションのフィルター配列を受け取ります。

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

フィルター操作

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

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

注意

API RemoveAllを呼び出すときは、filters 引数を指定 undefinedする必要があります。 その他の操作の場合は、定義する必要があります。

フィルター レベル

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

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

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

Note

フィルターの種類は、ビジュアル レベルの ITopNFilter フィルターでのみサポートされます。

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

レポート内のすべてのページに適用されるフィルターを取得または更新するには、レポート オブジェクトで関連する API を呼び出します。 次に例を示します。

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

すべてのページに適用されるフィルターを取得します。

let reportFilters = await report.getFilters();

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

すべてのページに対して、既存のフィルターと共に新しいフィルターを追加します。

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

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

すべてのページに適用されているフィルターを削除します。

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

ページ レベル フィルター

ページ レベル フィルターを取得または更新するには、次の操作を行います。

1. ターゲット ページのページ オブジェクトを取得します。 詳細については、「ページとビジュアルの取得」を参照してください。
2. ページ オブジェクトで、関連する API を呼び出します。

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

特定のページに適用されたフィルターを取得します。

let reportFilters = await page.getFilters();

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

特定のページに適用されたすべての既存のフィルターを、新しいフィルター セットに置き換えます。

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

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

特定のページに適用されたフィルターを削除します。

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

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

ビジュアル レベル フィルターを取得または更新するには、次の操作を行います。

1. ターゲット ビジュアルのビジュアル オブジェクトを取得します。 詳細については、「ページとビジュアルの取得」を参照してください。
2. ビジュアル オブジェクトで、関連する API を呼び出します。

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

特定のビジュアルに適用されたフィルターを取得します。

let reportFilters = await visual.getFilters();

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

特定のビジュアルのフィルターを置き換えます。 特定のフィルターと同じターゲット データ フィールドを持つフィルターが存在する場合は、指定されたフィルターに置き換えられます。 既存のフィルターと一致しないフィルターが追加されます。

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

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

特定のビジュアルに適用されたフィルターを削除します。

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

制限事項

• 高度なフィルターを構築するときに 2 つ以上の条件があると、未定義の動作が発生する可能性があります。

• IncludeExclude と Tuple フィルターの種類はサポートされていません。

• タプルと階層フィルター ターゲットはサポートされていません。

次のステップ

• レポート設定の構成
• レポート スライサーを制御する
• レポート レイアウトをカスタマイズする