Power BI レポートのビジュアルにブックマーク サポートを追加する

Power BI レポートのブックマークを使用すると、レポート ページの構成済みビューを取得して保存できます。 そうすると、必要に応じて、すばやく簡単に保存したビューに戻ることができます。 ブックマークには、選択とフィルターを含む構成全体が保存されます。

ブックマークの詳細については、「Power BI でブックマークを使用して分析情報を共有し、ストーリーを作成する」を参照してください。

ブックマークをサポートするビジュアル

ブックマークをサポートする Power BI ビジュアルの場合、正しい情報を保存して必要なときに提供できる必要があります。 ビジュアルで他のビジュアルとやりとりしたり、データ ポイントを選択したり、他のビジュアルをフィルター処理したりする場合は、ブックマークされた状態をビジュアルの filterState プロパティに保存する必要があります。

注意

ブックマークをサポートするビジュアルを作成するには、次のものが必要です。

  • Powerbi-visuals-utils-interactivityutils バージョン 3.0.0 以降 (フィルター処理ビジュアル、および InteractivityService を使用するあらゆるビジュアル用)。
  • ビジュアル API バージョン 1.11.0 以降 (InteractivityService ではなく SelectionManager を使用する、フィルター処理なしのビジュアル用)。
  • 使用しているバージョンを確認するには、pbiviz.json ファイルの apiVersion を確認してください。

レポート ブックマークで Power BI ビジュアルと Power BI がやりとりする方法

レポート ページ上に複数のブックマークを作成し、各ブックマークでそれぞれ異なるデータ ポイントを選択するとします。

まず、ビジュアルで 1 つまたは複数のデータ ポイントを選択します。 選択内容がビジュアルからホストに渡されます。 次に、[ブックマーク] ペイン[追加] を選択します。 Power BI では新しいブックマークの現在の選択内容が保存されます。

これを複数回行って新しいブックマークを作成します。 複数のブックマークを作成したら、それらを切り替えることができます。

ブックマークを選択するたびに、Power BI によって保存されたフィルターまたは選択状態が復元され、ビジュアルに渡されます。 レポート内のビジュアルは、ブックマークに格納されている状態に応じて、強調表示されるか、フィルター処理されます。 これを行うには、正しい選択状態がビジュアルからホストに渡される必要があります (たとえば、レンダリングされるデータ ポイントの色)。

新しい選択状態 (またはフィルター) は、update メソッドの options.jsonFilters プロパティを通じて伝達されます。 jsonFilters は、Advanced Filter または Tuple Filter とすることができます。

  • ビジュアルに選択したデータ ポイントが含まれている場合は、選択したブックマークのものになるように選択をリセットします。そのためには、ISelectionManager でコールバック関数 registerOnSelectCallback を使用します。
  • ビジュアルでデータを選択するためにフィルターを使用している場合は、選択したブックマークの対応する値になるようにフィルターをリセットします。

選択を使用するビジュアル

ビジュアルで選択を使用して他のビジュアルとやりとりする場合は、次の 2 つの方法のいずれかでブックマーク サポートを追加できます。

  • InteractivityService を使用して選択を管理するには、applySelectionFromFilter を使用します。 これは、より簡単で推奨される方法です。
  • ビジュアルで InteractivityService を使用しない場合は、SelectionManager を使用します。

InteractivityService を使用してブックマークの選択を復元する

ビジュアルで InteractivityService を使用する場合、ビジュアルでブックマークをサポートするために他のアクションは必要ありません。

ブックマークを選択すると、ビジュアルの選択状態がユーティリティによって自動的に処理されます。

SelectionManager を使用してブックマークの選択を復元する

InteractivityService を使用していない場合は、次のように ISelectionManager.registerOnSelectCallback メソッドを使用して、ブックマークの選択を保存および再呼び出しすることができます。

ブックマークを選択すると、Power BI によって、ビジュアルの callback メソッドが対応する選択と共に呼び出されます。

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        //called when a selection was set by Power BI
    });
);

ビジュアルの visualTransform メソッドでデータ ポイントを作成したとします。

datapoints は次のようになります。

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categorical.categories[0], i)
        .createSelectionId(),
    selected: false
});

これで、ご自分のデータ ポイントとして visualDataPoints が用意され、ids 配列が callback 関数に渡されます。

この時点で、ビジュアルでは ISelectionId[] 配列と、ご利用の visualDataPoints 配列内の選択を比較し、対応するデータ ポイントを選択済みとしてマークする必要があります。

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        visualDataPoints.forEach(dataPoint => {
            ids.forEach(bookmarkSelection => {
                if (bookmarkSelection.equals(dataPoint.selectionId)) {
                    dataPoint.selected = true;
                }
            });
        });
    });
);

データ ポイントを更新したら、filter オブジェクトに格納されている現在の選択状態が反映されます。 これで、データ ポイントがレンダリングされると、カスタム ビジュアルの選択状態がブックマークの状態と一致するようになります。

フィルターを使用するビジュアル

フィルターを持つビジュアルでブックマークをサポートするには、InteractivityService を使用します。

ビジュアルによって、データのフィルターが日付範囲で作成されるとします。 範囲の開始日と終了日として startDateendDate があります。

関連条件でデータをフィルター処理する場合、ビジュアルでは高度なフィルターが作成され、ホスト メソッド applyJsonFilter が呼び出されます。

ターゲットは、フィルター処理に使用されるテーブルです。

import { AdvancedFilter } from "powerbi-models";

const filter: IAdvancedFilter = new AdvancedFilter(
    target,
    "And",
    {
        operator: "GreaterThanOrEqual",
        value: startDate
            ? startDate.toJSON()
            : null
    },
    {
        operator: "LessThanOrEqual",
        value: endDate
            ? endDate.toJSON()
            : null
    });

this.host.applyJsonFilter(
    filter,
    "general",
    "filter",
    (startDate && endDate)
        ? FilterAction.merge
        : FilterAction.remove
);

ブックマークをクリックするたびに、カスタム ビジュアルによって update 呼び出しが取得されます。

update メソッドで、ビジュアルによってオブジェクト内のフィルターがチェックされます。

const filter: IAdvancedFilter = FilterManager.restoreFilter(
    && options.jsonFilters
    && options.jsonFilters[0] as any
) as IAdvancedFilter;

filter オブジェクトが null でない場合、オブジェクトからビジュアルにフィルター条件が復元されます。

const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];

if (jsonFilters
    && jsonFilters[0]
    && jsonFilters[0].conditions
    && jsonFilters[0].conditions[0]
    && jsonFilters[0].conditions[1]
) {
    const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
    const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);

    // apply restored conditions
} else {
    // apply default settings
}

その後、現在の条件に一致するように内部状態をビジュアルで変更する必要があります。 内部状態には、データ ポイントと視覚エフェクト オブジェクト (線や四角形など) が含まれます。

重要

上記のレポート ブックマークのシナリオでは、ビジュアルで applyJsonFilter を呼び出して他のビジュアルをフィルター処理する必要はありません。 これらは、既に Power BI によってフィルター処理されています。

タイムライン スライサー ビジュアルでは、範囲セレクターが、対応するデータ範囲に変更されます。

ビジュアルのフィルター状態を保存する

ブックマークのフィルターの条件を保存するだけでなく、その他のフィルターの側面を保存することもできます。

たとえば、タイムライン スライサーの場合、Granularity プロパティの値がフィルター状態として格納されます。 それにより、ブックマークを変更するときに、タイムラインの粒度 (日、月、年など) を変更できます。

filterState プロパティは、フィルターの側面をプロパティとして保存します。 ビジュアルを使用すると、さまざまな filterState 値をブックマークに格納できます。

プロパティ値をフィルター状態として保存するには、capabilities.json ファイル内でオブジェクト プロパティを "filterState": true として設定します。

次のステップ