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

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

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• report.json²
• definition\ フォルダー³
• プラットフォーム

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

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

レポート ファイル

.pbi\localSettings.js

現在のユーザーとローカル コンピューターにのみ適用されるレポート設定が含まれます。 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 参照を使用して、次のプロパティを指定する必要があります。

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": "[Semantic Model Id]",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": "EntityDataSource"
    }
  }
}

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

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

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

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

mobileState.json

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

report.json

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

definition\ フォルダー

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

。プラットホーム

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

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

PBIR 形式

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

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

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 という名前のフォルダーに保存されます。

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

既存のレポートを PBIR に変換する

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

1. Power BI Desktop で PBIP を開きます。

2. プレビュー機能が有効になっていることを確認します。

3. プロジェクトを [保存] します。 PBIR へのアップグレードを求めるメッセージが表示されます。

4. [アップグレード] を選択します。

   

   重要

   PBIR にアップグレードすると、UI から PBIR-Legacy に戻すことはできません。 PBIR-Legacy に戻すには、PBIP ファイルのコピーを保存します。

   Power BI Desktop では、PBIR にアップグレードする前にレポートのバックアップが自動的に作成されます。 このバックアップは、次のいずれかの場所で 30 日間保持されます。

   • Microsoft Store のバージョン: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
   • 実行可能なインストーラーのバージョン: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups

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

[ 現在の 形式を保持する] を選択した場合、デスクトップはアップグレードを再度求めるメッセージを表示しません。

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

PBIR 名前付け規則

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

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

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

レポート オブジェクト名をコピーする

レポート内の各オブジェクトは個別のフォルダーまたはファイルに保存されますが、フォルダーの名前が必ずしも明確であるとは限りません。 これを簡単にするために、レポート オブジェクト名 (ページ、ビジュアル、ブックマーク、フィルターを含む) の名前を Power BI からクリップボードに直接コピーできます。

PBIR Json スキーマ

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

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

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

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

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

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

一般的な PBIR エラー

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

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

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

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

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

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

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

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

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

PBIR は現在プレビュー段階です。 次の制限事項に留意してください。

• サービスの制限事項またはバグ
  • デプロイ パイプラインでデプロイできません。
  • コピーとして保存できません。
  • Power BI Report API を使用できない: レポートの複製、レポート内容の更新
  • Power BI 使用状況メトリック レポートを使用できません。
• ファイル数が 500 を超える大規模なレポートでは、次のような作成のパフォーマンスに関する問題が発生します (レポートの表示は影響を受けません)。
  • Power BI Desktop での保存
  • Fabric Git 統合での同期
• PBIR-Legacy から PBIR に変換されたレポートはロールバックできません。 ただし、変換の時点でバックアップが作成されます。
• "名前を付けて保存" 機能を使用して PBIP ファイルを PBIX ファイルに変換すると、PBIR レポートが PBIX ファイル内に埋め込まれ、PBIR の制限はすべて PBIX に引き継がれます。

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

• レポートあたり最大 1,000 ページ。
• ページあたり最大 300 ビジュアル。
• レポートあたり最大 1,000 リソース パッケージ ファイル。
• すべてのリソース パッケージ ファイルの最大サイズは 300 mb です。
• すべてのレポート ファイルの最大サイズは 300 mb です。

Fabric Git Integration API と Fabric REST API は、 サービスで現在適用されている形式を使用してレポートをエクスポートします。 レポートが PBIR 形式を使用して Fabric に作成またはインポートされた場合は、PBIR でエクスポートされます。 同様に、レポートが PBIR-Legacy の場合は、PBIR-Legacy 形式でエクスポートされます。

関連するコンテンツ

• Power BI Desktop プロジェクトのセマンティック モデル フォルダー
• Power BI Desktop プロジェクト