Power BI Desktop 项目报表文件夹

项目
10/22/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 支持三种类型的自定义视觉对象：

组织存储视觉对象 - 组织可以批准自定义视觉对象并将其部署到组织的 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 文件中有一个对应的条目，在预览期间，report.json 文件不支持编辑。只有导致 Power BI Desktop 在 report.json 中注册资源的已加载资源才支持编辑 RegisteredResources 文件。

semanticModelDiagramLayout.json

包含数据模型关系图，它描述了与报表关联的语义模型的结构。预览期间，此文件不支持外部编辑。

definition.pbir

包含报表和核心设置的总体定义。此文件还包含对报表使用的语义模型的引用。 Power BI Desktop 可以直接打开 pbir 文件，就像从 pbip 文件打开报表一样。如果存在使用 byPath 的相对引用，则打开 pbir 也会同时打开语义模型。

示例 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 引用时，必须指定以下属性：

properties	说明
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": null
    }
  }
}

当语义模型和报表共享同一工作区时，Fabric Git 集成始终使用对语义模型的 byPath 引用。

此文件还通过“version”属性指定支持的报表定义格式。

版本	支持的格式
1.0	报表定义必须以 PBIR-Legacy 格式存储在 report.json 文件中。
4.0 或更高版本	报表定义可以存储为 PBIR-Legacy（report.json 文件）或 PBIR（\definition 文件夹）。

有关详细信息，请参阅 definition.pbir 架构文档。

mobileState.json

包含在移动设备上呈现时的报表外观和行为设置。此文件不支持外部编辑。

report.json

此文件包含采用 Power BI 报表旧版格式 (PBIR-Legacy) 的报表定义，不支持外部编辑。

definition\ 文件夹

仅当 Power BI 项目使用 Power BI 增强型报表格式 (PBIR) 保存时，此文件夹才可用。它将替换 report.json 文件。

平台中添加用户。

Fabric 平台文件，其中包含对于建立和维护 Fabric 项目与 Git 之间的连接至关重要的属性。

若要了解详细信息，请参阅 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 预览功能中启用它：

转到“文件”>“选项和设置”>“选项”>“预览功能”，并勾选“使用增强型元数据格式(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	否	书签元数据，例如目标视觉对象和筛选器。有关详细信息，请参阅架构。
── bookmarks.json	否	书签元数据，例如书签顺序和组。有关详细信息，请参阅架构。
pages\	是	包含报表的所有页面的文件夹。
── [pageName]\	是	每页一个文件夹。
──── visuals\	否	包含页面的所有视觉对象的文件夹。
────── [visualName]\	否	每个视觉对象一个文件夹。
──────── mobile.json	否	视觉对象移动布局元数据，例如移动位置和格式设置。有关详细信息，请参阅架构。
──────── visual.json	是	视觉对象元数据，例如位置和格式、查询。有关详细信息，请参阅架构。
──── page.json	是	页面元数据，例如页面级别筛选器和格式设置。有关详细信息，请参阅架构。
── pages.json	否	页面元数据，例如页面顺序和活动页。有关详细信息，请参阅架构。
version.json	是	PBIR 文件版本以及其他因素决定了要加载的必需文件。有关详细信息，请参阅架构
reportExtensions.json	否	报表扩展，例如报表级别度量值。有关详细信息，请参阅架构
report.json	是	报表元数据，例如报表级别筛选器和格式设置。有关详细信息，请参阅架构

PBIR 命名约定

上表中方括号（[]）中的所有名称都遵循默认命名约定，但可以重命名为更易用的名称。默认情况下，页面、视觉对象和书签使用其报表对象名称作为其文件或文件夹名称。这些对象名称最初是一个 20 个字符的唯一标识符，例如“90c2e07d8e84e7d5c026”。

PBIR 名称属性的屏幕截图。

支持重命名每个 JSON 文件中的“name”属性，但可能会破坏报表内外的外部引用。对象名称和/或文件/文件夹名称必须包含一个或多个单词字符（字母、数字、下划线）或连字符。

重命名任何 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 文件的外部更改

可以使用代码编辑器（例如 Visual Studio Code 或外部工具）编辑 PBIR JSON 文件，只要该文件遵循 JSON 架构。可以直接在 Visual Studio Code 中轻松检测到使用错误的属性名称或类型：

提示 PBIR JSON 架构验证的屏幕截图。

对 PBIR 内容的外部更改可能会导致在 Power BI Desktop 中重新打开文件时出现错误。这些错误可以是两种类型：

“阻止错误”阻止 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 应用中。
- 不能使用部署管道进行部署。
- 不能另存为副本。
包含超过 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\ 文件夹

平台中添加用户。

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\ 文件夹

平台中添加用户。

PBIR 格式

启用 PBIR 格式预览功能

使用 PBIR 另存为项目

将现有 PBIP 转换为 PBIR

将 PBIR 报表发布到服务

PBIR 文件夹和文件

PBIR 命名约定

PBIR Json 架构

PBIR 批注

对 PBIR 文件的外部更改

常见 PBIR 错误

PBIR 注意事项和限制

相关内容

反馈

其他资源