レポート設定の構成

[アーティクル]
07/17/2024

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 プロパティでサポートされている値を確認できます。

財産	目に見える	拡大
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

フィルターウィンドウ

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

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

手記

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
            }
        }    
    }
};

手記

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

バー

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

アクションバー

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

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

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

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

手記

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

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

ステータスバー

ステータスバーには、キャンバスを拡大する機能を提供するキャンバスズームコントローラーが保持されます。

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

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

ロケールの設定

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

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

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

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

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

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

手記

レポートの読み込み後にロケール設定を変更することはできません。レポートのロケール設定を変更するには、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 クリックの既定の動作を防ぎ、イベント dataHyperlinkClicked 発生させます。

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

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

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

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
    }
};

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

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

使用できるコントラストモード:

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 - ユーザーはレポートを表示、編集、保存できます。
- ユーザーは、[名前を付けて保存]を使用して、レポートのコピー保存できます。
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");

考慮事項と制限事項

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

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

ブックマークを使用してユーザーのエクスペリエンスを向上させる
Power BI でレポートテーマを適用する
コントロールレポートフィルター
コントロールレポートスライサー

次の方法で共有

レポート設定の構成

構成情報を指定する

設定をカスタマイズする

ペイン

フィルターウィンドウ

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

バー

アクションバー

ステータスバー

ロケールの設定

透明な背景

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

表示されるイベントを表示する

エラーメッセージ

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

既定のページ

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

スライサーの読み込み時

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

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

ズームレベル

編集モードで開く

編集モードを構成する

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

考慮事項と制限事項

その他のリソース

次の方法で共有

レポート設定の構成

構成情報を指定する

設定をカスタマイズする

ペイン

フィルター ウィンドウ

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

バー

アクション バー

ステータス バー

ロケールの設定

透明な背景

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

表示されるイベントを表示する

エラー メッセージ

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

既定のページ

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

スライサーの読み込み時

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

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

ズーム レベル

編集モードで開く

編集モードを構成する

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

考慮事項と制限事項

関連コンテンツ

その他のリソース

フィルターウィンドウ

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

アクションバー

ステータスバー

エラーメッセージ

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

ズームレベル