Power BI Desktop 專案報表資料夾

發行項
12/18/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\ folder³
.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 資料夾中。 Power BI Desktop 會自動載入 AppSource 和組織視覺效果。

RegisteredResources\

子資料夾，其中包含報表專屬的資源檔，以及使用者所載入的資源檔，例如自訂主題、影像和自訂視覺效果 (pbiviz 檔案)。

開發人員會負責此處的檔案，可進行變更。例如，您可以變更檔案，Power BI Desktop 重新啟動之後，新檔案會載入報表中。此資料夾可以解鎖一些實用的案例，例如：

使用公開結構描述，在 Power BI Desktop 外部撰寫自訂主題。
變更多個報表上的資源檔，以套用批次變更。例如，您可以切換公司自訂主題、在淺色和深色主題之間變更，以及變更標誌圖片。

每個資源檔在 report.json 檔案中都必須有對應的項目，在預覽期間不支援編輯。只有已載入的資源才支援對 RegisteredResources 檔案進行編輯，讓 Power BI Desktop 在 report.json 中註冊資源。

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 參照時，必須指定下列屬性：

屬性	描述
connectionString	參照遠端語意模型的連接字串。
pbiModelDatabaseName	遠端語意模型標識碼。
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 參考。如果您想要強制在即時連線模式下開啟報表（例如，使用報表層級的量值來進行工作），您可以擁有多個定義*.pbir 檔案，例如一個使用 byPath 連線，另一個則使用 byConnection 連線。然而，透過 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 報表舊版格式的報表定義 (PBIR-Legacy)，且不支援外部編輯。

definition\ 資料夾

只有當 Power BI 專案是使用 Power BI 增強報表格式 (PBIR) 儲存時，才能使用此資料夾。 report.json 檔案會被替換。

功能。

保存屬性的網狀架構平台檔案，對於建立和維護 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 Integration。這牽涉到將工作區連線到 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

檔案/資料夾	必要	描述
書籤\	No	包含報表所有書籤檔案的資料夾。
── [bookmarkName].bookmark.json	No	書籤中繼資料，例如目標視覺效果和篩選。如需相關資訊，請參閱結構描述。
── bookmarks.json	No	書籤中繼資料，例如書籤順序和群組。如需相關資訊，請參閱結構描述。
pages\	Yes	包含報表所有頁面的資料夾。
── [pageName]\	Yes	每頁一個資料夾。
──── visuals\	No	包含頁面所有視覺效果的資料夾。
────── [visualName]\	No	每個視覺效果一個資料夾。
──────── mobile.json	No	視覺效果行動裝置版面配置中繼資料，例如行動裝置位置和格式設定。如需相關資訊，請參閱結構描述。
──────── visual.json	Yes	視覺效果中繼資料，例如位置與格式設定、查詢。如需相關資訊，請參閱結構描述。
──── page.json	Yes	頁面中繼資料，例如頁面層級篩選和格式設定。如需相關資訊，請參閱結構描述。
── pages.json	No	頁面中繼資料，例如頁面順序和使用中頁面。如需相關資訊，請參閱結構描述。
version.json	Yes	PBIR 檔案版本及其他因素會決定要載入的必要檔案。如需相關資訊，請參閱結構描述
reportExtensions.json	No	報表延伸模組，例如報表層級量值。如需相關資訊，請參閱結構描述
report.json	Yes	報表中繼資料，例如報表層級篩選和格式設定。如需相關資訊，請參閱結構描述

重要

某些報表元數據檔案，例如 visual.json 或 bookmarks.json，可能會與語意模型中的數據值一起儲存。例如，如果您將篩選套用至字段『Company』 = 『Contoso』的視覺效果，則『Contoso』值將會保存為元數據的一部分。這也適用於其他設定，例如交叉分析篩選器選取、矩陣自定義欄寬度，以及特定系列的格式設定。

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 結構描述驗證的螢幕擷取畫面。

重新開啟 Power BI Desktop 中的檔案時，對 PBIR 內容的外部變更可能會導致錯誤。這些錯誤可能有兩種類型：

封鎖錯誤會禁止 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 目前為預覽版。請記住下列要點：

服務限制/Bug
- 行動檢視不會顯示在Power BI Apps 中。
- 隱藏的頁面會在Power BI Apps 導覽中公開。
- 無法透過部署管線進行部署。
- 無法儲存為副本。
具有超過 500 個檔案的大型報表會遇到撰寫效能問題 (報表檢視不受影響)，其中包括：
- 在 Power BI Desktop 中儲存
- Fabric Git Integration 中的同步處理
一旦報表從 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 Integration 和 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 考量與限制

相關內容

意見反應

其他資源