Папка отчета проекта Power BI Desktop

В этой статье описываются файлы и вложенные папки в папке отчета проекта Microsoft Power BI Desktop. Файлы и вложенные папки здесь представляют отчет Power BI. В зависимости от проекта папка отчета может включать:

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. Изменения в файлах RegisteredResources поддерживаются только для уже загруженных ресурсов, которые заставляют Power BI Desktop регистрировать ресурс в файле report.json.

semanticModelDiagramLayout.json

Содержит схемы модели данных, описывающие структуру семантической модели, связанной с отчетом. Этот файл не поддерживает внешнее редактирование.

определение.pbir

Содержит общее определение отчета и основных параметров. Этот файл также содержит ссылку на семантику модели, используемую отчетом. Power BI Desktop может открыть PBIR-файл напрямую, как если бы отчет был открыт из PBIP-файла. При открытии PBIR-файла семантическая модель также открывается вместе, если используется относительная ссылка byPath.

Пример определения.pbir:

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    }    
  }
}

Определение включает datasetReference свойство, которое ссылается на семантическую модель, используемую в отчете. Ссылка может быть одной из следующих:

byPath — указывает относительный путь к папке целевой семантической модели. Абсолютные пути не поддерживаются. Косая черта (/) используется в качестве разделителя папок. При использовании Power BI Desktop также открывает семантику модели в режиме полного редактирования.

byConnection — указывает подключение к семантической модели в рабочей области Fabric с помощью строки подключения. Если используется ссылка byConnection, Power BI Desktop не открывает семантическую модель в режиме редактирования.

Используя ссылку byConnection , необходимо указать следующие свойства:

Свойство Описание
connectionString Строка подключения, ссылающаяся на семантическую модель в рабочем пространстве Fabric.

Пример с использованием byConnection:

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "Data Source=\"powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName]\";initial catalog=[SemanticModelName];access mode=readonly;integrated security=ClaimsToken;semanticmodelid=[SemanticModelId]"
    }
  }
}

При развертывании отчета с помощью REST API Fabric необходимо указать только это semanticmodelid свойство. Рассмотрим пример.

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

Внимание

При развертывании отчета с помощью REST API Fabric необходимо использовать byConnection ссылки. Это не следует путать с режимом хранения семантической модели, например DirectQuery. В datasetReference отчете указывается только семантическая модель, к которой подключается отчет, он не определяет, как эта модель хранит или получает доступ к его данным.

Несколько файлов *.pbir

Если семантическая модель и отчет используют одну и ту же рабочую область, интеграция Fabric Git всегда экспортирует определения со ссылкой byPath на семантику модели. Если вы хотите принудительно открыть отчет в режиме прямого подключения (например, для работы с метриками уровня отчета), можно иметь несколько различных *.pbir файлов, например, один с подключением byPath и другой с подключением byConnection. Интеграция Fabric Git обрабатывает только файл definition.pbir и игнорирует все остальные файлы *.pbir. Однако эти файлы могут сосуществовать в одном репозитории.

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

Файл definition.pbir также задает поддерживаемые форматы определения отчета с помощью свойства version.

Версия Поддерживаемые форматы
1.0 Определение отчета должно храниться как PBIR-Legacy в файле report.json.
4.0 или выше Определение отчета может храниться как PBIR-Legacy (файлreport.json) или PBIR (папка определения).

Дополнительные сведения см. в документе схемы definition.pbir.

mobileState.json

Содержит параметры внешнего вида и поведения отчета при отрисовке на мобильном устройстве. Этот файл не поддерживает внешнее редактирование.

report.json

Этот файл содержит определение отчета в устаревшем формате отчета Power BI (PBIR-Legacy) и не поддерживает внешнее редактирование.

папка definition\

Эта папка доступна только в том случае, если проект Power BI сохраняется с помощью расширенного формата отчета Power BI (PBIR). Он заменяет файл report.json .

платформа

Файл платформы Fabric, содержащий свойства, жизненно важные для установления и поддержания соединения между элементами Fabric и Git.

Дополнительные сведения см. в статье об интеграции Git с автоматически созданными системными файлами.

Формат PBIR

Сохранение файлов проекта Power BI (PBIP) с помощью расширенного формата отчетов Power BI (PBIR) значительно улучшает отслеживание изменений и разрешение конфликт слияния с помощью правильно отформатированных JSON-файлов.

Снимок экрана: понятные диффы PBIR.

Каждая страница, визуальный элемент, закладка и т. д. организована в отдельный отдельный файл в структуре папок. Этот формат идеально подходит для разрешения конфликтов при совместной разработке.

Снимок экрана: дружественная папка PBIR.

В отличие от PBIR-Legacy (report.json), PBIR — это общедоступный задокументированный формат, поддерживающий изменения из других приложений, не Power BI. Каждый файл имеет общедоступную схему JSON, которая не только документирует файл, но и позволяет редакторам кода, таким как Visual Studio Code, выполнять синтаксическую проверку во время редактирования.

Ниже приведены некоторые из возможных сценариев, доступных в PBIR:

  • Скопируйте страницы, визуальные элементы и закладки между отчетами.
  • Обеспечение согласованности набора визуальных элементов на всех страницах путем копирования и вставки визуальных файлов.
  • Простой поиск и замена в нескольких файлах отчетов.
  • Применение пакетного редактирования для всех визуальных элементов с помощью скрипта (например, скрытие фильтров визуального уровня)

Сохраните как проект с помощью PBIR

При сохранении проекта с помощью PBIR отчет сохраняется в папке с именем \definition внутри папки отчета:

Снимок экрана папки с определениями в папке отчета PBIP.

Дополнительные сведения о структуре папок PBIR.

Папка и файлы 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
Файл или папка Обязательное поле Описание
Закладки\ Нет Папка, содержащая все файлы закладок отчета.
[bookmarkName].bookmark.json Нет Метаданные закладки, такие как целевые визуальные элементы и фильтры.
Более подробная информация о схеме.
── bookmarks.json Нет Метаданные закладок, такие как порядок закладок и группы.
Более подробная информация о схеме.
Страниц Да Папка, содержащая все страницы отчета.
'' [pageName]\ Да Одна папка на страницу.
''''' визуальные элементы\ Нет Папка, содержащая все визуальные элементы страницы.
────── [visualName]\ Нет Одна папка на визуальный элемент.
──────── mobile.json Нет Метаданные визуального макета мобильного устройства, такие как положение и форматирование мобильных устройств.
Более подробная информация о схеме.
─────── visual.json Да Визуальные метаданные, такие как положение и форматирование, запрос.
Более подробная информация о схеме.
──── page.json Да Метаданные страницы, такие как фильтры уровня страницы и форматирование.
Более подробная информация о схеме.
* pages.json Нет Метаданные страниц, такие как порядок страниц и активная страница.
Более подробная информация о схеме.
version.json Да Версия файла PBIR, среди прочего, определяет необходимые файлы для загрузки.
Дополнительные сведения о схеме
reportExtensions.json Нет Расширения отчетов, такие как показатели уровня отчета.
Дополнительные сведения о схеме
report.json Да Метаданные отчета, такие как фильтры уровня отчета и форматирование.
Дополнительные сведения о схеме

Внимание

Некоторые файлы метаданных отчета, такие как visual.json или bookmarks.json, можно сохранить с помощью значений данных из семантической модели. Например, если применить фильтр к визуальному элементу поля "Компания" = Contoso, значение Contoso будет сохраняться в составе метаданных. Это также относится к другим конфигурациям, таким как выбор срезов, ширина настраиваемых столбцов матрицы и форматирование для определенных рядов.

Правила именования PBIR

Все имена в квадратных скобках ([]) в предыдущей таблице соответствуют соглашению об именовании по умолчанию, но их можно переименовать в более понятные имена. По умолчанию страницы, визуальные элементы и закладки используют имя объекта отчета в качестве имени файла или папки. Эти имена объектов изначально являются уникальным идентификатором 20 символов, например "90c2e07d8e84e7d5d5c026".

Снимок экрана свойства имени PBIR.

Переименование свойства name в каждом JSON-файле поддерживается, но может нарушить внешние ссылки как внутри, так и за пределами отчета. Имя объекта и (или) имя файла или папки должно состоять из одного или нескольких символов слова (букв, цифр, символов подчеркивания) или дефисов.

После переименования всех PBIR-файлов или папок необходимо перезапустить Power BI Desktop. После перезапуска Power BI Desktop сохранит исходные имена файлов или папок при сохранении.

Копирование имени объекта отчета

Каждый объект в отчете сохраняется в отдельной папке или файле, но имя папки не всегда очевидно. Чтобы упростить эту задачу, можно скопировать имя любого объекта отчета (включая страницы, визуальные элементы, закладки и фильтры) непосредственно из Power BI в буфер обмена.

Снимок экрана: отчет со стрелкой, указывающей от одного из визуальных элементов на имя соответствующего файла.

  1. Перейдите в раздел «Файл > Параметры и настройки > Настройки отчета > Объекты отчета и включите настройку Копировать имена объектов при щелчке правой кнопкой мыши по объектам отчета. Это необходимо сделать только один раз.

    Снимок экрана настроек отчета объектов.

  2. Щелкните правой кнопкой мыши любой объект отчета и выберите "Копировать имя объекта".

    Скриншот отчета рабочего стола с выбранным именем объекта копии.

С помощью имени объекта, скопированного в буфер обмена, его можно легко ввести в строку поиска проводника Windows или Visual Studio Code, чтобы найти или определить имя объекта в папке PBIR.

Снимок экрана: панель поиска с именем объекта.

Схемы JSON PBIR

Каждый ФАЙЛ JSON PBIR включает объявление схемы JSON в верхней части документа. Этот URL-адрес схемы является общедоступным и может использоваться для получения дополнительных сведений о доступных свойствах и объектах для каждого файла. Кроме того, он предоставляет встроенную технологию IntelliSense и проверку при редактировании с помощью редакторов кода, таких как Visual Studio Code.

Снимок экрана: всплывающая подсказка схемы JSON PBIR.

URL-адрес схемы также определяет версию документа, которая, как ожидается, изменится по мере развития определения отчета.

Здесь публикуются все схемы JSON.

Аннотации PBIR

Заметки можно включать в определение отчета в виде пар "имя-значение" для каждого visual, page и report. Хотя Power BI Desktop игнорирует эти заметки, они могут быть ценными для внешних приложений, таких как скрипты.

Например, можно указать defaultPage для отчета в файле report.json, который затем может быть использован скриптом развертывания.

{
  "$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-файлах

Поддерживаемые ФАЙЛЫ JSON PBIR можно изменить в редакторе кода, например Visual Studio Code или другом внешнем средстве, пока проект остается открытым в Power BI Desktop. При сохранении файлов Power BI Desktop обнаруживает изменения и отображает баннер "Применить внешние изменения". Выберите "Применить внешние изменения ", чтобы перезагрузить определение отчета без закрытия и повторного открытия проекта.

Перед редактированием PBIR-файлов во внешнем режиме сохраните все изменения в Power BI Desktop. Если в Power BI Desktop есть несохранённые изменения при применении внешних изменений, Power BI Desktop предупреждает, что эти несохранённые изменения будут перезаписаны. Полный рабочий процесс и ограничения см. в разделе "Изменение PBIP-файлов за пределами Power BI Desktop".

PBIR-файлы должны соответствовать их схемам JSON. VS Code определяет такие проблемы, как неподдерживаемое имя свойства или неправильный тип свойства:

Снимок экрана: проверка схемы JSON PBIR.

Внешние изменения содержимого PBIR могут привести к ошибкам при применении изменений или открытии файлов в Power BI Desktop. Эти ошибки могут быть двух типов:

Блокирующие ошибки не позволяют Power BI Desktop загрузить изменения отчета. Эти ошибки определяют проблему и файл, который необходимо исправить перед применением изменений еще раз:

Снимок экрана ошибки блокировки PBIR.

Ошибки, такие как недопустимая схема или отсутствующие обязательные свойства, блокируют ошибки. Чтобы определить эти ошибки, откройте файл в VS Code и проверьте сообщения проверки схемы.

Неблокирующие ошибки не препятствуют открытию отчета Power BI Desktop и автоматически разрешаются.

Снимок экрана: ошибка неблокирования PBIR запроса.

Недопустимая конфигурация activePageName является примером неблокирующей ошибки, которую Power BI Desktop исправляет автоматически. Предупреждение дает возможность просмотреть исправление перед сохранением отчета и перезаписать внешнее определение.

Распространенные ошибки PBIR

Сценарий:После изменения названий папок визуальных элементов или страниц, визуальный элемент или страница больше не отображаются при открытии отчета.

Решение: Убедитесь, соответствует ли имя соглашению об именовании. Если это не так, Power BI Desktop игнорирует файл или папку и обрабатывает его как частные файлы пользователей.

Сценарий:Новые объекты отчета называются по-разному от других. Например, большинство папок страниц называются ReportSection0e71dafbc949c0853608, а некоторые — "1b3c2ab12b603618070b".

Решение: PBIR принял новое соглашение об именовании для каждого объекта, но применяется только к новым объектам. При сохранении существующего отчета в формате PBIP необходимо сохранить текущие имена, чтобы предотвратить разрывы ссылок. Если вы хотите обеспечить согласованность, допускается пакетное переименование с использованием скрипта.

Сценарий:я скопировал файл закладок, и после сохранения большая часть конфигурации закладок была удалена.

Решение: Это поведение намеренно, закладки отчетов фиксируют состояние страницы отчета вместе со всеми его визуальными элементами. Так как захваченное состояние исходит из другой страницы отчета с различными визуальными элементами, любые недопустимые визуальные элементы удаляются из конфигурации закладки. Если вы также копируете зависимые визуальные элементы и страницы, закладка сохраняет свою конфигурацию.

Сценарий:Я скопировал папку страницы из другого отчета и обнаружил ошибку с сообщением", "Значения свойства "pageBinding.name" должны быть уникальными".

Решение: Объект pageBinding необходим для поддержки детализации и подсказки страницы. Поскольку на него могут ссылаться другие страницы, имя должно быть уникальным в рамках отчета. На только что скопированной странице назначьте уникальное значение для устранения ошибки. После июня 2024 г. эта ситуация больше не является проблемой, так как имя pageBinding по умолчанию является GUID.

Преобразование существующего отчета в PBIR

PBIR обычно доступен и является форматом отчета по умолчанию. Вы по-прежнему можете открывать отчеты, использующие PBIR-Legacy в Power BI Desktop и служба Power BI. Когда вы изменяете и сохраняете отчет PBIR-Legacy, Power BI автоматически и без уведомления преобразует его в PBIR.

Перед преобразованием Power BI создает резервную копию отчета:

  • Power BI Desktop сохраняет резервную копию в течение 30 дней в одном из следующих расположений:
    • Версия Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Версия исполняемого установщика: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • служба Power BI сохраняет резервную копию PBIR-Legacy в течение 28 дней. Чтобы восстановить его, откройте параметры отчета из рабочей области и выберите "Восстановить как PBIR-Legacy". Эта резервная копия создается только для отчетов, преобразованных непосредственно в служба Power BI.

Восстановление резервной копии PBIR-Legacy не предотвращает другое преобразование. Чтобы сохранить отчет в PBIR-Legacy формате, не изменяйте его в служба Power BI или используйте выпуск Power BI Desktop, выпущенный до сентября 2026 года.

Рекомендации и ограничения PBIR

Помните о следующих рекомендациях и ограничениях:

  • Визуальные автоматические фильтры сохраняются в PBIR-файле visual.json только после развертывания области фильтров по крайней мере один раз при редактировании отчета.
  • Если Power BI не преобразует отчет PBIR-Legacy в PBIR при редактировании и сохранении, преобразование столкнулось с проблемой продукта. Создайте запрос на поддержку , чтобы сообщить о проблеме.

Ограничения размера PBIR, применяемые службой:

  • 1000 максимальных страниц на отчет.
  • 1000 максимальных визуальных элементов на страницу.
  • Максимум 1000 файлов пакетов ресурсов на один отчет.
  • Максимальный размер 300 МБ для всех файлов пакета ресурсов.
  • Максимальный размер всех файлов отчета составляет 300 МБ.

Внимание

Если вы достигнете указанных выше ограничений, следует рассмотреть возможность оптимизации отчета. См. документ по оптимизации Power BI.

Интеграция Fabric с Git и REST API Fabric позволяют экспортировать определения отчетов в формате PBIR.

Связанный контент

  • Последнее обновление: