レポート設定の構成

[アーティクル]
09/17/2023

Power BI クライアント API を使用すると、Power BI 分析をアプリケーションに埋め込むことができます。このクライアント側ライブラリを使用して Power BI レポートを埋め込む場合は、そのレポートに関する情報を API に提供します。

構成オブジェクトを使用して、Power BI レポートに関する情報を格納できます。レポートを埋め込むとき、そのオブジェクトを API に渡します。

API にレポートへのアクセス権を付与するだけでなく、構成オブジェクトを使用してレポートの外観と動作をカスタマイズすることもできます。たとえば、フィルターの可視性、ナビゲーションアクセス、および場所の設定を構成オブジェクトで調整できます。

次のセクションでは、Power BI コンテンツを埋め込んで構成する方法について説明します。

構成情報を指定する

IReportLoadConfiguration インターフェイスには、レポートに関する Power BI クライアント API に構成オブジェクトが提供できるプロパティが表示されます。

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

このインターフェイスの必須パラメーターの説明と、レポートを埋め込む方法を示すコード例については、「レポートを埋め込む」を参照してください。

設定のカスタマイズ

次のセクションでは、プロパティを settings 使用して、埋め込み Power BI レポートの外観と動作を調整する方法について説明します。レポートが既に読み込まれているときにレポート設定を更新するには、メソッドを使用します report.updateSettings 。詳細については、「実行時にレポート設定を更新する」を参照してください。

ペイン

次のコードに示すように、1 つの panes プロパティを使用して Power BI レポート内のすべてのペインの外観を制御します。

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

次の表から、各 panes プロパティがサポートする値を確認できます。

プロパティ	Visible	[展開済み]
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

フィルターペイン

既定では、フィルターウィンドウが表示されます。このウィンドウを非表示にする場合は、次のコードに filterPaneEnabled 示すように、プロパティを使用します。

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Note

panes プロパティは、プロパティをfilterPaneEnabled置き換えます。下位互換性を filterPaneEnabled 維持するために、プロパティは引き続き存在します。ただし、これら 2 つのプロパティを一緒に使用することは避ける必要があります。

既定では、ページナビゲーション矢印は埋め込みレポートに表示されます。これらの矢印を非表示にするには、次のコードに navContentPaneEnabled 示すように、プロパティを使用します。

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

注意

panes プロパティは、プロパティをnavContentPaneEnabled置き換えます。下位互換性を navContentPaneEnabled 維持するために、プロパティは引き続き存在します。ただし、これら 2 つのプロパティを一緒に使用することは避ける必要があります。

レポートの下部にページナビゲーションウィンドウが表示され、新しい垂直ページウィンドウを使用するには、プロパティを position 設定できます。

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Note

を使用してページナビゲーションウィンドウの位置を updateSettings変更することはできません。

Bars

プロパティを使用して、アクションバーとステータスバーの表示を bars 設定します。

アクションバー

次のコードは、アクションバーを表示します。

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

または、ビューモードでは、URL パラメーターを actionBarEnabled 使用することもできます。

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

注意

ビューモードでは、アクションバーは、organizationシナリオの埋め込みでのみサポートされます。

ビューモードのアクションバーの場合は、Azure AD アプリケーションのアクセス許可を有効に UserState.ReadWrite.All することをお勧めします。エンドユーザーが自分のお気に入りにレポートを追加したり、個人用ブックマークや永続的なフィルターを有効にしたりするには、このアクセス許可が必要です。

ステータスバー

ステータスバーには、キャンバスのズームコントローラーが保持されます。これにより、キャンバスを拡大できます。

次のコードは、ステータスバーを表示します。

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

ロケール設定

プロパティを localeSettings 使用して、埋め込みレポートの言語と書式設定を指定します。

の localeSettings プロパティはlanguage、それぞれ 2 文字の 2 つの部分で構成され、ハイフンで区切られます。

language は、Power BI がローカライズに使用する言語を定義します。言語の例としては、 en (英語)、 es (スペイン語)、 tr (トルコ語) などがあります。
locale は、Power BI が日付、通貨、およびその他の関連コンテンツに使用するテキスト書式を定義します。ロケールの例としては、米国 (英語)、 ES (スペイン)、 TR (Türkiye) などがあります。

使用可能な言語とリージョンの一覧については、「サポートされている言語」を参照してください。

次のコードは、これらの localeSettingsに特定の値を割り当てます。

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Note

レポートの読み込み後にロケール設定を変更することはできません。レポートロケールの設定を変更するには、を呼び出 powerbi.reset(element)して iframe をリセットし、レポートをもう一度埋め込みます。

透明な背景

既定では、埋め込みコンテンツの背景は白で、灰色の余白が表示されます。必要に応じて、埋め込みコンテンツに透明な背景を付けることができます。その後、埋め込みコンテンツを含む HTML div 要素に目的のスタイルを適用できます。その後、 div 要素のスタイルが表示されます。

埋め込みコンテンツの背景を透明にするには、次のコードを使用します。

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

ハイパーリンクのクリック動作

表内のハイパーリンクの動作を制御したり、すぐに使用できるマトリックスビジュアルを設定したりできます。既定では、ハイパーリンクは新しいウィンドウを開きます。

使用できる動作モードを次に示します。

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL が新しい閲覧コンテキストに読み込まれます。
NavigateAndRaiseEvent - URL が新しい閲覧コンテキストに読み込まれ、イベントが dataHyperlinkClicked 発生します。
RaiseEvent - URL クリックと raise dataHyperlinkClicked イベントの既定の動作を防ぎます。

次のコードを使用して、イベントを発生させるためにリンクの動作を変更します。

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

イベントはdataHyperlinkClicked、すぐに使えるテーブルまたはマトリックスビジュアルでハイパーリンクがクリックされ、動作がまたは RaiseEventであるNavigateAndRaiseEvent場合に発生します。

report.on('dataHyperlinkClicked', () => {
    ...
});

イベントの処理の詳細については、「イベントを処理する方法」を参照してください。

ビジュアルでレンダリングされたイベント

レンダリングされた各ビジュアルのイベントをリッスンできます。既定では、ビジュアルレンダリングイベントは無効になっています。

イベントをトリガーするには、次のコードを visualRendered 使用します。

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

visualRenderedビジュアルがレンダリングされ、レポート設定でがvisualRenderedEvents有効になると、イベントが発生します。

report.on('visualRendered', () => {
    ...
});

イベントの処理の詳細については、「イベントを処理する方法」を参照してください。

注意

ビジュアルはユーザーの操作によってレンダリングされる可能性があるため、必要な場合にのみこのイベントを有効にすることをお勧めします。

エラーメッセージ

埋め込みレポートにカスタマイズされたエラーメッセージを表示する場合は、プロパティを hideErrors 使用して、既定の Power BI 埋め込みエラーメッセージを非表示にします。その後、コードは、アプリの設計に合わせてエラーイベントを処理できます。既定のエラーのオーバーライドの詳細については、「既定のエラーメッセージをオーバーライドする」を参照してください。

既定のエラーメッセージを非表示にするには、次のコードを使用します。

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

オプションをカスタマイズする

次のセクションでは、追加のプロパティを使用して、埋め込み Power BI レポートの外観と動作をさらにカスタマイズする方法について説明します。

既定のページ

埋め込みレポートのどのページを最初に表示するかを制御できます。既定では、最初のページは最後に変更したページです。これは、レポートを最後に保存した時点でアクティブなページでした。この動作をオーバーライドするには、プロパティを pageName 使用し、表示するページの名前を指定します。ただし、その名前のページが Power BI に存在しない場合、開く要求は失敗します。

次のコードは、特定のページを表示するようにアプリを構成する方法を示しています。

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

読み込みフィルターの場合

アプリが埋め込みレポートに適用するフィルターを制御できます。既定では、レポートでは最初にレポートに保存したフィルターが使用されます。ただし、フィルターを調整する場合は、次の 2 つのオプションがあります。

保存されたフィルターと共に使用する追加のフィルターを構成します。次のコードは、プロパティを使用して追加の filters フィルターを追加する方法を示しています。
```
let embedConfig = {
    ...
    filters: [...]
};
```
保存したフィルターを新しいセットに置き換えます。メソッドは setFilters 、レポートのフィルターを動的に変更する方法を提供します。段階的埋め込み中にこのメソッドを使用する場合は、レポートが最初に適用するフィルターをオーバーライドできます。フィルターの構築とメソッドの使用の詳細については、「レポートフィルターのsetFilters制御」を参照してください。

読み込みスライサーの場合

アプリが埋め込みレポートに適用するスライサーの状態を制御できます。既定では、API はレポートに保存したスライサーを使用します。ただし、次のコードに slicers 示すように、プロパティを使用して既存のスライサーの状態を変更できます。

embedConfig = {
    ...
    slicers: slicerArray,
};

スライサーの状態の変更の詳細については、「レポートスライサーを制御する」を参照してください。

ブックマークの読み込み時

プロパティを bookmark 使用すると、埋め込みレポートにブックマークを適用できます。ブックマークを使用してレポートページの現在構成されているビューをキャプチャする方法の詳細については、「ブックマーク」を参照してください。

ブックマーク名または状態を指定することで、使用するブックマークを指定できます。ブックマーク名を指定した場合、Power BI レポートには、その名前の保存済みブックマークが含まれている必要があります。

プロパティは bookmark 型 IApplyBookmarkRequest. です。次のコードは、この型の定義を示しています。

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

このコードは、名前でブックマークを指定する方法を示しています。

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

このコードは、状態でブックマークを指定する方法を示しています。

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

テーマとハイコントラストモード

埋め込みコンテンツで使用するテーマとコントラストのレベルを制御できます。既定では、埋め込んだコンテンツは既定のテーマで、コントラストがゼロで表示されます。特定のテーマまたはコントラストレベルを構成することで、この動作をオーバーライドできます。テーマの詳細については、「レポートテーマを適用する」を参照してください。

使用できるコントラストモードを次に示します。

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

次の行のようなコードを使用して、特定のテーマを構成します。

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

次のコードは、 None既定のコントラストレベルをオーバーライドする方法を示しています。

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

注意

API では、テーマとコントラストレベルを同時に適用することはできません。両方のプロパティを構成する場合、API は指定したコントラストレベルを使用しますが、設定は theme 無視します。

ズームレベル

アクセシビリティドキュメントチェックレポートのズームレベルを調整する方法の詳細については、こちらを参照してください。

編集モードで開く

既定では、埋め込んだレポートはビューモードで表示されます。ただし、この動作をオーバーライドして、レポートを編集モードで開くことができます。モードを切り替えることもできます。

編集モードを構成する

埋め込みレポートを編集モードで開くには、プロパティを viewMode プロパティと共に permissions 使用します。

プロパティには、次の viewMode 値を割り当てることができます。

View - レポートを表示モードで開きます。
Edit - レポートを編集モードで開きます。

プロパティには、次の値を permissions 割り当てることができます。

Read - ユーザーはレポートを表示できます。
ReadWrite - ユーザーはレポートを表示、編集、保存できます。
Copy - ユーザーは、[名前を付けて保存] を使用してレポートのコピー を保存できます。
Create - ユーザーは新しいレポートを作成できます。
All - ユーザーは、レポートのコピーを作成、表示、編集、保存、および保存できます。

編集モードで開くコンテンツを構成する場合は、次の permissions コードに示すように、編集に適した値をプロパティに割り当てます。

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

注意

構成する値は permissions 、取得した埋め込みトークンに十分な特権がある場合にのみ機能します。埋め込みトークンの詳細については、「埋め込みトークンを作成する」を参照してください。

編集モードと表示モードを切り替える

埋め込みコンテンツの開始モードを指定するだけでなく、編集モードと表示モードを動的に切り替えることができます。

コンテンツが編集モードで、表示モードに切り替える場合は、次の JavaScript コードを使用します。

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

コンテンツがビューモードで、編集モードに切り替える場合は、次の JavaScript コードを使用します。

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

考慮事項と制限事項

埋め込みコンテンツを構成するときは、次の点を考慮してください。

アクションバーが表示されている場合、ページナビゲーションの位置を変更することはできません。アクションバーの詳細については、こちらを参照してください。
プロパティでプロパティをbarssetting使用する場合は、「Bars」で説明されているように、埋め込みコンテンツが編集モードの場合にのみ、API によって構成が適用されます。コンテンツがビューモードの場合、API は設定を無視します bars 。
プロパティを viewMode 使用して編集モードでコンテンツを表示する場合は、次の 2 つの追加手順を実行する必要があります。
- プロパティを使用してアクセス許可レベルを permissions 構成します。そのアクセス許可レベルでは、コンテンツを変更するための適切なアクセス権をユーザーに付与する必要があります。たとえば、ユーザーのRead,値をpermissions割り当てると、コンテンツを編集できなくなります。
- 生成する埋め込みトークンに、編集をサポートする特権があることを確認します。たとえば、API の値view,を持つトークンをaccessLevel取得した場合、編集モードでコンテンツを表示できません。
panes プロパティは、次settingsのプロパティを置き換えます。
- filterPaneEnabled
- navContentPaneEnabled
プロパティをpanes使用してフィルターまたはページナビゲーションの可視性を構成する場合は、アプリでまたは navContentPaneEnabled プロパティをfilterPaneEnabled使用しないでください。
API では、埋め込みコンテンツにテーマとコントラストレベルを同時に適用することはできません。プロパティと contrastMode プロパティを使用して両方のオプションをtheme構成すると、API は埋め込みコンテンツで値を使用contrastModeします。ただし、API は設定を無視します theme 。
埋め込みレポートにブックマークを適用する場合は、プロパティを bookmark 使用できます。そのプロパティにブックマーク名を指定した場合、API はその名前を持つブックマークが存在する場合にのみブックマークを使用できます。同様に、プロパティを pageName 使用して開始ページを指定した場合、API はそのページが指定された名前で存在する場合にのみ表示できます。名前を構成する前に、Report getPages メソッドなどのアクセサーメソッドを使用して、その名前のコンポーネントが存在するかどうかをチェックすることを検討してください。

Share via

レポート設定の構成

構成情報を指定する

設定のカスタマイズ

ペイン

フィルターペイン

ページナビゲーションウィンドウ

Bars

アクションバー

ステータスバー

ロケール設定

透明な背景

ハイパーリンクのクリック動作

ビジュアルでレンダリングされたイベント

エラーメッセージ

オプションをカスタマイズする

既定のページ

読み込みフィルターの場合

読み込みスライサーの場合

ブックマークの読み込み時

テーマとハイコントラストモード

ズームレベル

編集モードで開く

編集モードを構成する

編集モードと表示モードを切り替える

考慮事項と制限事項

次の手順

その他のリソース

Share via

レポート設定の構成

構成情報を指定する

設定のカスタマイズ

ペイン

フィルター ペイン

ページ ナビゲーション ウィンドウ

Bars

アクション バー

ステータス バー

ロケール設定

透明な背景

ハイパーリンクのクリック動作

ビジュアルでレンダリングされたイベント

エラー メッセージ

オプションをカスタマイズする

既定のページ

読み込みフィルターの場合

読み込みスライサーの場合

ブックマークの読み込み時

テーマとハイ コントラスト モード

ズーム レベル

編集モードで開く

編集モードを構成する

編集モードと表示モードを切り替える

考慮事項と制限事項

次の手順

その他のリソース

フィルターペイン

ページナビゲーションウィンドウ

アクションバー

ステータスバー

エラーメッセージ

テーマとハイコントラストモード

ズームレベル