Power BI Desktop プロジェクトレポートフォルダー

[アーティクル]
08/13/2024

重要

Power BI Desktop プロジェクトは現在、プレビュー段階です。

この記事では、Microsoft Power BI Desktop プロジェクトのレポート フォルダー内のファイルとサブフォルダーについて説明します。ここでのファイルとサブフォルダーは、Power BI レポートを表します。プロジェクトに応じて、レポートフォルダーには次のものが含まれる場合があります。

.pbi\
- localSettings.json
CustomVisuals\
StaticResources\
- RegisteredResources\
semanticModelDiagramLayout.json
definition.pbir¹
mobileState.json
report.json²
definition\ フォルダー³
.platform

1 - このファイルは必須です。
2 - このファイルは、PBIR-Legacy 形式に保存する場合に必須です。
3 - このファイルは、PBIR 形式に保存する場合に必須です。

すべてのプロジェクトレポートフォルダーに、ここで説明するすべてのファイルとサブフォルダーが含まれているわけではありません。

レポートファイル

.pbi\localSettings.json

現在のユーザーとローカルコンピューターにのみ適用されるレポート設定が含まれます。 gitIgnore、またはその他のソース管理の除外対象に含める必要があります。 Git では、既定でこのファイルが無視されます。

詳しくは、localSettings.json スキーマのドキュメントを参照してください。

CustomVisuals\

レポート内のカスタムビジュアルのメタデータを含むサブフォルダー。 Power BI では、次の 3 種類のカスタムビジュアルがサポートされています。

組織ストアビジュアル - 組織は、組織用のカスタムビジュアルを承認して Power BI にデプロイできます。詳細については、「組織ストア」を参照してください。
AppSource Power BI ビジュアル - "パブリックカスタムビジュアル" とも呼ばれます。これらのビジュアルは、Microsoft AppSource から入手できます。レポート開発者は、これらのビジュアルを Power BI Desktop から直接インストールできます。
カスタムビジュアルファイル - "プライベートカスタムビジュアル" とも呼ばれます。ファイルは、pbiviz パッケージをアップロードすることでレポートに読み込むことができます。

プライベートカスタムビジュアルのみが CustomVisuals フォルダーに読み込まれます。 AppSource および組織のビジュアルは、Power BI Desktop によって自動的に読み込まれます。

RegisteredResources\

カスタムテーマ、イメージ、カスタムビジュアル (pbiviz ファイル) など、レポートに固有のリソースファイルを含み、ユーザーによって読み込まれるサブフォルダー。

開発者がこのファイルを担当し、変更がサポートされます。たとえば、ファイルを変更することができ、Power BI Desktop の再起動後に、新しいファイルがレポートに読み込まれます。このフォルダーは、次のようないくつかの有用なシナリオに対応できます。

パブリックスキーマを使用して、Power BI Desktop の外部でカスタムテーマを作成する。
複数のレポートでリソースファイルを変更して、バッチ変更を適用する。たとえば、企業のカスタムテーマの切り替え、淡色と濃色のテーマ間の変更、ロゴイメージの変更を行うことができます。

すべてのリソースファイルでは、report.json ファイルに対応するエントリが必要です。プレビュー中には、編集はサポートされません。 RegisteredResources ファイルの編集は、Power BI Desktop で report.json にリソースが登録される原因となる、既に読み込まれているリソースに対してのみサポートされます。

semanticModelDiagramLayout.json

レポートに関連付けられているセマンティックモデルの構造を説明するデータモデル図が含まれています。 プレビュー中は、このファイルで外部編集はサポートされません。

definition.pbir

レポートとコア設定の全体的な定義が含まれます。このファイルは、レポートで使用されるセマンティックモデルへの参照も保持します。 Power BI Desktop では、pbip ファイルからレポートを開いた場合と同じように、pbir ファイルを直接開くことができます。 pbir を開くと、byPath を使用した相対参照がある場合、セマンティックモデルも一緒に開きます。

definition.pbir の例:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    },
    "byConnection": null
  }
}

定義には、レポートで使用されるセマンティックモデルを参照する datasetReference プロパティが含まれています。参照は次のいずれかになります。

byPath - ターゲットのセマンティックモデルフォルダーへの相対パスを指定します。絶対パスはサポートされていません。スラッシュ (/) は、フォルダー区切り記号として使用されます。使用すると、Power BI Desktop はセマンティックモデルも完全編集モードで開きます。

byConnection - 接続文字列を使用して、Power BI サービス内のリモートセマンティックモデルを指定します。 byConnection 参照が使用されているときは、Power BI Desktop が編集モードでセマンティックモデルを開きません。

byConnection 参照を使用して、次のプロパティを指定する必要があります。

プロパティ	説明
connectionString	リモートセマンティックモデルを参照する接続文字列。
pbiModelDatabaseName	リモートセマンティックモデル ID。
connectionType	接続の種類。サービスのリモートセマンティックモデルの場合、この値は `pbiServiceXmlaStyleLive` である必要があります。
pbiModelVirtualServerName	値 `sobe_wowvirtualserver` を持つ必要がある内部プロパティ。

byConnection の使用例:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": null,
    "byConnection": {
      "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/WorkpaceName;Initial Catalog=SemanticModelName;Integrated Security=ClaimsToken",
      "pbiServiceModelId": null,
      "pbiModelVirtualServerName": "sobe_wowvirtualserver",
      "pbiModelDatabaseName": "e244efd3-e253-4390-be28-6be45d9da47e",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": "EntityDataSource"
    }
  }
}

セマンティックモデルとレポートが同じワークスペースを共有する場合、Fabric Git Integration では常にセマンティックモデルへの byPath 参照が使用されます。ライブ接続でレポートを強制的に開く (たとえば、レポートレベルのメジャーを操作する) 場合は、byPath 接続を持つファイルと byConnection 接続を持つファイルなど、複数の定義 *.pbir ファイルを作成できます。ただし、Fabric Git を使用して定義をインポートする場合、definition.pbir ファイルのみが無視されません。

  ├── definition\
  ├── StaticResources\
  ├── .platform
  ├── definition-liveConnect.pbir
  └── definition.pbir

このファイルでは、'version' プロパティを使用して、サポートされているレポート定義の形式も指定します。

バージョン	サポートされるフォーマット
1.0	レポート定義は、report.json ファイルに PBIR-Legacy として保存する必要があります。
4.0 以降	レポート定義は、PBIR-Legacy (report.json ファイル) または PBIR (\definition フォルダー) に保存できます。

詳しくは、definition.pbir スキーマのドキュメントを参照してください。

mobileState.json

モバイルデバイスでレンダリングするときのレポートの外観と動作の設定が含まれます。このファイルでは、外部編集はサポートされていません。

report.json

このファイルには、Power BI Report Legacy 形式 (PBIR-Legacy) のレポート定義が含まれています。外部編集はサポートされません。

definition\ フォルダー

このフォルダーは、Power BI プロジェクトが Power BI 拡張レポート形式 (PBIR) で保存されている場合にのみ使用できます。これは report.json ファイルに置き換わるものです。

.platform

Fabric アイテムと Git 間の接続を確立および保守するのに不可欠なプロパティを保持する Fabric プラットフォームファイル。

詳しくは、Git 統合の自動生成されるシステムファイルに関する記事を参照してください。

PBIR 形式

重要

プレビュー段階で、PBIR の制限事項をすべて検討してください。

Power BI 拡張レポート形式 (PBIR) を使用して Power BI プロジェクトファイル (PBIP) を保存すると、適切に書式設定された JSON ファイルを使用することで、変更の追跡とマージ競合解決が大幅に向上します。

フレンドリ PBIR の差分のスクリーンショット。

ページ、ビジュアル、ブックマークなどはそれぞれ、フォルダー構造内の個々のファイルに個別に整理されています。この形式は、共同開発の競合解決に最適です。

フレンドリ PBIR フォルダーのスクリーンショット。

PBIR-Legacy (report.json) とは異なり、PBIR は、Power BI 以外のアプリケーションからの変更をサポートする公開文書形式です。各ファイルにはパブリック JSON スキーマがあり、ファイルを文書化するだけでなく、Visual Studio Code などのコードエディターで、編集中に構文検証を実行することもできます。

PBIR により使用できるようになったシナリオをいくつか次に示します。

レポート間でのページ/ビジュアル/ブックマークのコピーする。
ビジュアルファイルをコピーして貼り付けることで、すべてのページで一連のビジュアルの一貫性を確保する。
複数のレポートファイル間で簡単に検索および置換する。
スクリプトを使用してすべてのビジュアルにバッチ編集を適用する (ビジュアルレベルフィルターの非表示など)

PBIR 形式のプレビュー機能を有効にする

PBIR を使った Power BI プロジェクトとしての保存は、現在プレビュー段階です。使用する前に、Power BI Desktop プレビュー機能で有効にする必要があります。

[ファイル] > [オプションと設定] > [オプション] > [プレビュー機能] に移動し、[Store reports using enhanced metadata format (PBIR)] (拡張メタデータ形式 (PBIR) を使用してレポートを保存する) の横にあるボックスをオンにします。

PBIR を使用してプロジェクトとして保存する

PBIR プレビュー機能を有効にすると、プロジェクトを保存したときに、レポートがレポートフォルダー内の \definition という名前のフォルダーに保存されます。

レポート pbip フォルダー内の定義フォルダーのスクリーンショット。

詳しくは、「PBIR フォルダー構造」を参照してください。

既存の PBIP を PBIR に変換する

PBIR-Legacy 形式を使用した PBIP が既にある場合は、次のように PBIR に変換できます。

Power BI Desktop で PBIP を開きます。
プレビュー機能が有効になっていることを確認します。
プロジェクトを [保存] します。 PBIR へのアップグレードを求めるメッセージが表示されます。
[アップグレード] を選択します。

重要

一度 PBIR にアップグレードすると、PBIR-Legacy に戻すことはできません。 PBIR-Legacy に戻す可能性がある場合は、最初に PBIP ファイルのコピーを保存してください。

既存の PBIR-Legacy ファイル (report.json) は、レポートの PBIR 表現を含む \definition フォルダーに置き換えられます。

形式に [現在を保持] を選択した場合、デスクトップによってアップグレードを求めるメッセージは表示されなくなります。

PBIR レポートをサービスに発行する

プレビュー段階では、PBIR 形式でレポートを発行する唯一の方法が、Fabric Git 統合を使用することです。それには、ワークスペースを Git リポジトリに接続し、PBIR レポートをプッシュする必要があります。これにより、後の段階で、サービスワークスペースと同期できるようになります。

サービス内の PBIR に既存のレポートを変換したい場合は、次の手順に従います。

ワークスペースを Git に接続します。
Git リポジトリをローカルファイルシステムにクローンします。
definition.pbir ファイルを開いて、Power BI Desktop でレポートを開きます。
レポートを保存し、PBIR にアップグレードすることを選択します。
変更をコミットして Git に同期させます。
Git からの最新の変更でワークスペースを更新します。

PBIR フォルダーとファイル

レポート定義は、次の構造の definition\ フォルダー内に保存されます。

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

ファイル/フォルダー	必須	説明
bookmarks\	いいえ	レポートのすべてのブックマークファイルを保持するフォルダー。
── [bookmarkName].bookmark.json	いいえ	ブックマークメタデータ (ターゲットビジュアルやフィルターなど)。詳細情報: schema。
── bookmarks.json	いいえ	ブックマークメタデータ (ブックマークの順序、グループなど)。詳細情報: schema。
pages\	はい	レポートのすべてのページを保持するフォルダー。
── [pageName]\	はい	ページごとに 1 つのフォルダー。
──── visuals\	いいえ	ページのすべてのビジュアルを保持するフォルダー。
────── [visualName]\	いいえ	ビジュアルごとに 1 つのフォルダー。
──────── mobile.json	いいえ	ビジュアルモバイルレイアウトメタデータ (モバイルの位置と書式設定など)。詳細情報: schema。
──────── visual.json	はい	ビジュアルメタデータ (位置と書式設定、クエリなど)。詳細情報: schema。
──── page.json	はい	ページメタデータ (ページレベルフィルター、書式設定など)。詳細情報: schema。
── pages.json	いいえ	ページメタデータ (ページ順序、アクティブなページなど)。詳細情報: schema。
version.json	はい	いくつかの要因の中でも特に、PBIR ファイルバージョンによって、読み込まれる必要なファイルが決まります。詳細情報: schema
reportExtensions.json	いいえ	レポート拡張機能 (レポートレベルのメジャーなど)。詳細情報: schema
report.json	はい	レポートメタデータ (レポートレベルのフィルター、書式設定など)。詳細情報: schema

重要

visual.json や bookmarks.jsonなどの一部のレポートメタデータファイルは、セマンティックモデルのデータ値と共に保存される場合があります。たとえば、フィールド 'Company' = 'Contoso' のビジュアルにフィルターを適用すると、値 'Contoso' はメタデータの一部として保持されます。これは、スライサーの選択、マトリックスのカスタム列の幅、特定の系列の書式設定などの他の構成にも適用されます。

PBIR 名前付け規則

前の表の角かっこ ([]) 内のすべての名前は既定の名前付け規則に従いますが、わかりやすい名前に変更できます。既定では、ページ、ビジュアル、ブックマークは、レポートオブジェクト名をファイル名またはフォルダー名として使用します。これらのオブジェクト名は、最初は 20 文字の一意識別子 ('90c2e07d8e84e7d5c026' など) です。

PBIR name プロパティのスクリーンショット。

各 JSON ファイル内の 'name' プロパティの名前を変更することはサポートされていますが、レポートの内部と外部の両方で外部参照が壊れる可能性があります。オブジェクト名またはファイル/フォルダー名は、1 つ以上の単語文字 (文字、数字、アンダースコア) またはハイフンで構成されている必要があります。

PBIR ファイルまたはフォルダーの名前を変更した後、Power BI Desktop を再起動する必要があります。再起動すると、Power BI Desktop は保存時に元のファイル名またはフォルダー名を保持します。

PBIR Json スキーマ

各 PBIR JSON ファイルには、ドキュメントの先頭に JSON スキーマ宣言が含まれます。このスキーマ URL はパブリックにアクセス可能であり、各ファイルで使用可能なプロパティとオブジェクトの詳細を確認するために使用できます。さらに、Visual Studio Code などのコードエディターでの編集時に、組み込みの IntelliSense と検証機能を提供します。

PBIR JSON スキーマのヒントプロンプトのスクリーンショット。

スキーマ URL ではドキュメントのバージョンも定義されます。これは、レポート定義の進化に伴って変わることが予想されます。

JSON スキーマはすべて、こちらに公開されています。

PBIR 注釈

注釈は、各 visual、 page 、および reportのレポート定義内に名前と値のペアとして含めることができます。 Power BI Desktop はこれらの注釈を無視しますが、スクリプトなどの外部アプリケーションにとって価値があります。

たとえば、 report.json ファイルでレポートの defaultPage を指定すると、デプロイスクリプトで使用できます。

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  ...
  "annotations": [
    {
      "name": "defaultPage",
      "value": "c2d9b4b1487b2eb30e98"
    }
  ]
}

PBIR ファイルへの外部からの変更

PBIR JSON ファイルは、JSON スキーマに従っている限り、Visual Studio Code や外部ツールなどのコードエディターを使用して編集できます。プロパティ名や型の使用が誤っている場合、その誤りは Visual Studio Code で直接簡単に検出できます。

PBIR JSON スキーマ検証プロンプトのスクリーンショット。

PBIR コンテンツに対する外部からの変更により、Power BI Desktop でファイルを再度開くときにエラーが発生する可能性があります。これらのエラーは 2 種類あります。

ブロックエラー: これにより、Power BI Desktop がレポートを開くことができなくなります。これらのエラーは、発生している問題と、再度開く前に修正しなければならない問題のあるファイルを特定するのに役立ちます。

PBIR ブロックエラープロンプトのスクリーンショット。

無効なスキーマ、必要なプロパティが見つからない、などのエラーは、ブロックエラーと見なされます。これらのエラーは、Visual Studio Code でファイルを開き、スキーマエラーを調べることで簡単に特定できます。

非ブロッキングエラー: このエラーが発生しても、Power BI Desktop でレポートを開くことができます。これは自動的に解決されるエラーです。

PBIR 非ブロッキングエラープロンプトのスクリーンショット。

自動的に修正される非ブロッキングエラーの例としては、無効な activePageName 構成などがあります。警告が必要なのは、自動修正によってレポートが保存されないようにするためです。これにより、作業が失われるのを防ぐことができます。

一般的な PBIR エラー

シナリオ:ビジュアルまたはページフォルダー名の名前を変更すると、レポートを開くときにビジュアルまたはページが表示されなくなります。

解決策: 名前が名前付け規則に準拠しているかどうかを確認します。準拠していない場合、Power BI Desktop では、そのファイルまたはフォルダーは無視され、プライベートユーザーファイルとして処理されます。

シナリオ:新しいレポートオブジェクトの名前は、他のレポートオブジェクトとは異なります。たとえば、ほとんどのページフォルダーは "ReportSection0e71dafbc949c0853608" という名前で、一部のフォルダーは "1b3c2ab12b603618070b" という名前です。

解決策: PBIR では、すべてのオブジェクトに新しい名前付け規則が採用されましたが、これは新しいオブジェクトにのみ適用されます。既存のレポートを PBIP として保存する場合は、参照が破損するのを防ぐために、現在の名前を保持する必要があります。一貫性が必要な場合は、スクリプトによるバッチ名前変更が許可されています。

シナリオ:ブックマークファイルをコピーし、保存すると、ブックマーク構成の大部分が削除されました。

解決策: この動作は意図的なものです。レポートブックマークは、レポートページの状態を、そのすべてのビジュアルと共にキャプチャします。キャプチャされた状態は、異なるビジュアルを含む別のレポートページからのものであるため、無効なビジュアルはすべて、ブックマーク構成から削除されます。依存ビジュアルとページもコピーすれば、ブックマークの構成は維持されます。

シナリオ:別のレポートからページフォルダーをコピーし、「'pageBinding.name' プロパティの値は一意である必要があります」というエラーが発生しました。

解決策: ドリルスルーとページのヒントをサポートするには、pageBinding オブジェクトが必要です。これは他のページによって参照される可能性があるため、名前はレポート内で一意である必要があります。エラーを解決するには、新しくコピーしたページで一意の値を割り当てます。 2024 年 6 月以降、pageBinding 名は既定で GUID になり、この状況は問題ではなくなりました。

PBIR に関する考慮事項と制限事項

PBIR は現在プレビュー段階です。次の点に注意してください。

サービスの制限事項/バグ
- モバイルビューは Power BI Apps には表示されません。
- 非表示のページは、Power BI Apps ナビゲーションで公開されます。
- デプロイパイプラインでデプロイできません。
- コピーとして保存できません。
ファイル数が 500 を超える大規模なレポートでは、次のような作成のパフォーマンスに関する問題が発生します (レポートの表示は影響を受けません)。
- Power BI Desktop での保存
- Fabric Git 統合での同期
PBIR-Legacy から PBIR に変換されたレポートはロールバックできません。
"名前を付けて保存" 機能を使用して PBIP ファイルを PBIX ファイルに変換すると、PBIR レポートが PBIX ファイル内に埋め込まれ、PBIR の制限はすべて PBIX に引き継がれます。

サービスによって適用される PBIR サイズの制限:

レポートあたり最大 1,000 ページ。
ページあたり最大 300 ビジュアル。
ブックマークファイルごとに最大 5 MB。
ファイルごとに最大 1 MB。
レポートあたり最大 1,000 リソースパッケージファイル。
すべてのリソースパッケージファイルの最大サイズは 300 MB。
すべてのレポートファイルの最大サイズは 20 MB。

パブリックプレビュー期間中、レポート定義をエクスポートするとき、Fabric Git 統合と Fabric REST API では引き続き PBIR-Legacy (report.json) が使用されます。ただし、レポートが PBIR 形式で Fabric にインポートされると、両方の機能が PBIR 形式でレポート定義をエクスポートし始めます。

次の方法で共有

Power BI Desktop プロジェクトレポートフォルダー

レポートファイル

.pbi\localSettings.json

CustomVisuals\

RegisteredResources\

semanticModelDiagramLayout.json

definition.pbir

mobileState.json

report.json

definition\ フォルダー

.platform

PBIR 形式

PBIR 形式のプレビュー機能を有効にする

PBIR を使用してプロジェクトとして保存する

既存の PBIP を PBIR に変換する

PBIR レポートをサービスに発行する

PBIR フォルダーとファイル

PBIR 名前付け規則

PBIR Json スキーマ

PBIR 注釈

PBIR ファイルへの外部からの変更

一般的な PBIR エラー

PBIR に関する考慮事項と制限事項

フィードバック

その他のリソース

次の方法で共有

Power BI Desktop プロジェクト レポート フォルダー

レポート ファイル

.pbi\localSettings.json

CustomVisuals\

RegisteredResources\

semanticModelDiagramLayout.json

definition.pbir

mobileState.json

report.json

definition\ フォルダー

.platform

PBIR 形式

PBIR 形式のプレビュー機能を有効にする

PBIR を使用してプロジェクトとして保存する

既存の PBIP を PBIR に変換する

PBIR レポートをサービスに発行する

PBIR フォルダーとファイル

PBIR 名前付け規則

PBIR Json スキーマ

PBIR 注釈

PBIR ファイルへの外部からの変更

一般的な PBIR エラー

PBIR に関する考慮事項と制限事項

関連するコンテンツ

フィードバック

その他のリソース

Power BI Desktop プロジェクトレポートフォルダー

レポートファイル