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

  • [アーティクル]

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

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

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

手記

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

顧客のに を埋め込むレポートで同様のエクスペリエンスを作成する方法については、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 - 既定では、キャプチャされたブックマークの状態によって、現在のページの状態のみが保存されます。 すべてのページの状態をキャプチャするには、trueに設定 allPages オプション capture メソッドを呼び出します。
  • - カスタマイズされたビジュアル使用して現在の状態をキャプチャするには、 オプションを に設定して メソッドを呼び出します。

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

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

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

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

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

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

applyState(state: string): Promise<void>

例えば：

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

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

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

例えば：

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>

手記

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

スライド ショーのプレゼンテーション モードに切り替える

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

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

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

制限

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

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

関連コンテンツ