ブックマークを使用してユーザーのエクスペリエンスを向上させる

  • [アーティクル]

Power BI のレポート ブックマークを使用すると、埋め込みレポート ページの現在の状態 (すべてのフィルターとそのビジュアルの状態を含む) をキャプチャできます。 後でレポートを開くと、ブックマークを選択して、レポートを保存された状態に復元できます。 開発者は、Power BI クライアント API を使用してブックマークをキャプチャして適用することで、ユーザー エクスペリエンスを制御できます。

保存されたブックマークには、レポートの一部として保存されたブックマーク、またはレポートのリアルタイム状態としてキャプチャされたブックマークを指定できます。 レポートを読み込むときに保存したブックマークを適用する場合は、ブックマークの名前またはその状態を指定して、使用するブックマークを指定できます。 名前でブックマークを指定する場合、レポートには同じ名前の保存済みブックマークが含まれている必要があります。

この記事では、ブックマークをサポートするレポートを埋め込むために必要なさまざまな API 設定について説明します。

Note

組織用に埋め込んだレポートでは、レポート コンシューマーは、レポートの状態をキャプチャして個人用ブックマークを作成し、ブックマークを選択してその状態にすばやく戻ります。 詳細については、「 個人用ブックマーク 」を参照してください。

顧客向けに埋め込んだレポートで同様のエクスペリエンスを作成する方法については、Power BI 埋め込み分析プレイグラウンドのレポート ビューのキャプチャ ショーケースを参照してください。

Power BI でブックマークを使用する方法の詳細については、「Power BI Desktopでブックマークを作成する」を参照してください。

Power BI を埋め込むときに個人用ブックマークを使用する方法については、「 個人用ブックマーク」を参照してください。

レポート ブックマークの使用方法

次のセクションでは、Power BI クライアント API を使用してレポート ブックマークを操作する方法について説明します。

レポートのブックマークを管理する

レポートのブックマークを管理するには、埋め込みレポート インスタンスの プロパティを使用bookmarksManagerします。

BookmarksManager クラスには、次のメソッドがあります。

  • getBookmarks - レポートに関連付けられている保存済みブックマークの一覧を返します。

  • apply - 以前に保存したブックマークをレポートに名前で適用します。

  • capture - レポートの現在の状態を表す base64 シリアル化文字列をキャプチャして返します。

  • applyState 以前にキャプチャした base64 シリアル化状態のブックマークをレポートに適用します。

  • play - レポートのブックマークのスライド ショー表示モードを制御します。

レポート ブックマークにアクセスする

個々のブックマークにアクセスするには、 メソッドを getBookmarks 使用してオブジェクトの ReportBookmark 一覧にアクセスします。 クラスには ReportBookmark 、次のプロパティがあります。

  • name - レポート ブックマークの一意識別子。

  • displayName - [ブックマーク] ウィンドウに表示されるレポート ブックマーク の表示名。

  • state - レポート ブックマークの状態の base64 シリアル化。 これを保存し、 メソッドを使用してレポートに bookmarksManager.applyState 適用できます。

  • children - レポート ブックマーク グループを表すオブジェクトの ReportBookmark 一覧 (存在する場合)。

レポート ブックマーク API を使用する

埋め込みレポートでは、開発者は次のことができます。

保存されたレポート ブックマークの一覧を取得する

レポートに関連付けられている保存済みブックマークの一覧を取得するには、レポートの プロパティによって返される BookmarksManager オブジェクトの bookmarksManager メソッドを呼び出getBookmarksします。

メソッドは getBookmarks 次のように定義されます。

getBookmarks(): Promise<models.IReportBookmark[]>

次に例を示します。

let bookmarks = await report.bookmarksManager.getBookmarks();

レポートの読み込み時またはセッション中に名前で保存されたブックマークを適用する

以前に保存したブックマークを、そのブックマーク名を使用してレポートに適用するには、レポートの プロパティによって返される BookmarksManager オブジェクトの bookmarksManager メソッドを呼び出applyします。

詳細については、「 レポート設定の構成」を参照してください。

メソッドは apply 次のように定義されます。

apply(bookmarkName: string): Promise<void>

次に例を示します。

await report.bookmarksManager.apply("Bookmark1234");

現在のビューをブックマーク オブジェクトとしてキャプチャして取得する

レポートの現在の状態を base64 文字列としてキャプチャするには、BookmarksManager オブジェクトの メソッドを呼び出captureします。 メソッドは capture 、特定のレポートに IReportBookmark 保存されていないブックマークを表す オブジェクトを返します。 プロパティを IReportBookmark.state 使用して、ブックマークの状態を識別する base64 文字列を取得します。この文字列は、読み込み時間または実行時に後でレポートに適用できます。

メソッドは capture 次のように定義されます。

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

次に例を示します。

let capturedBookmark = await report.bookmarksManager.capture();

ブックマーク オプションをキャプチャする

オブジェクトを ICaptureBookmarkOptions メソッドに capture 渡すこともできます。

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - 既定では、キャプチャされたブックマークの状態では、現在のページの状態のみが保存されます。 すべてのページの状態をキャプチャするには、 オプションを に設定して メソッドをallPagestrue呼び出しますcapture。
  • personalizeVisuals- カスタマイズされたビジュアルで現在の状態をキャプチャするには、 オプションを に設定して capture メソッドをpersonalizeVisualstrue呼び出します。

たとえば、次のコードは、パーソナライズされたビジュアルを含むすべてのページの状態をキャプチャします。

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

レポートの読み込み時またはセッション中にキャプチャされたブックマークの状態を適用する

以前にキャプチャしたブックマークの状態をレポートに適用するには、BookmarksManager オブジェクトの メソッドを使用applyStateします。

詳細については、「 レポート設定の構成」を参照してください。

メソッドは applyState 次のように定義されます。

applyState(state: string): Promise<void>

次に例を示します。

await report.bookmarksManager.applyState(capturedBookmark.state);

レポート ブックマークが適用されたときに追加のロジックを実行する

レポート ブックマークが適用されたタイミングを確認するには、レポート オブジェクトの メソッドをbookmarkApplied呼び出onしてイベントをリッスンします。

次に例を示します。

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

[ブックマーク] ウィンドウの表示と非表示を切り替える

[Power BI ブックマーク ] ウィンドウを表示または非表示にするには、レポート設定の プロパティを更新 panes します。

[ブックマーク] ウィンドウを表示する

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

[ブックマーク] ウィンドウを非表示にする

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

レポート設定の更新の詳細については、「レポート設定の 構成」を参照してください。

ブックマークのスライド ショー モードを開始または終了する

レポートのブックマークのスライド ショー表示モードを制御するには、BookmarksManager オブジェクトの メソッドを呼び出playします。 詳細については、「 スライド ショーとしてのブックマーク」を参照してください。

メソッドは play 次のように定義されます。

play(playMode: models.BookmarksPlayMode): Promise<void>

Note

ブックマークスライド ショー モードに入る前に、 getBookmarks API を使用してレポートに少なくとも 1 つのブックマークがあることを確認します。

スライド ショーのプレゼンテーション モードに入る

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

スライド ショーのプレゼンテーション モードを終了する

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

制限事項

  • ブックマーク API を使用すると、レポートに対する特定の変更によってエラーや予期しない結果が発生する可能性があります。 その 1 つの例として、レポートからレポート フィルターを削除する方法があります。 エラーを回避するには、対応するフィルター カードが存在する必要があります。 フィルターを削除する代わりに、その値を に設定します All。 削除または変更されたフィルターがわからない場合は、変更をレポートに適用した後にブックマークを再キャプチャします。

  • 埋め込みセッションによって作成された、または更新フィルターの追加操作によって追加された読み込みフィルターなどのフィルターは、ブックマーク状態でキャプチャされますが、現在のセッションでのみ適用されます。 この制限を克服するには、フィルターを値と共 All にレポートに保存し、 更新フィルターの更新操作を使用して埋め込みセッションで変更する必要があります。

次のステップ