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

Важно!

Проекты Power BI Desktop в настоящее время находятся в предварительной версии.

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

• PBI\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• ^{report.json 2}
• определение\ папка³
• .платформа

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

semanticModelDiagramLayout.json

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

definition.pbir

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

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

JSON

{
  "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:

JSON

{
  "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 REST API необходимо использовать ссылки byConnection.

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

Markdown

  ├── definition\
  ├── StaticResources\
  ├── .platform
  ├── definition-liveConnect.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

Важно!

На этапе предварительной версии рассмотрите все ограничения PBIR.

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

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

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

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

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

Включение функции предварительной версии формата PBIR

Сохранение в качестве проекта Power BI с помощью PBIR в настоящее время находится в предварительной версии. Прежде чем использовать его, включите его в предварительных версиях Power BI Desktop:

Перейдите в раздел "Параметры файла>" и ">Параметры > предварительной версии" и установите флажок рядом с отчетами Store с помощью расширенного формата метаданных (PBIR).

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

С включенной функцией предварительной версии PBIR при сохранении проекта отчет сохраняется в папке с именем \definition внутри папки отчета:

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

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

Если у вас уже есть PBIP с помощью формата PBIR-Legacy, его можно преобразовать в PBIR следующим образом:

1. Откройте PBIP в Power BI Desktop.

2. Убедитесь, что функция предварительной версии включена.

3. Сохраните проект. Появится запрос на обновление до PBIR.

4. Выберите Обновить.

   

   Важно!

   После обновления до PBIR вы не сможете вернуться к PBIR-Legacy. Если вы считаете, что вам может потребоваться вернуться к PBIR-Legacy, сначала сохраните копию PBIP-файлов.

Существующий файл PBIR-Legacy (report.json) заменяется папкой \definition , содержащей представление отчета PBIR.

Если вы выберете значение "Сохранить текущий формат", рабочий стол снова не запрашивает обновление.

Публикация отчета PBIR в службе

На этапе предварительной версии единственный способ публикации отчета с форматом PBIR — с помощью интеграции Fabric Git. Это включает подключение рабочей области к репозиторию Git и отправку отчета PBIR в него, который затем можно синхронизировать с рабочей областью службы на более позднем этапе.

Если вы хотите преобразовать существующий отчет в PBIR в службе, выполните следующие действия.

1. Подключите рабочую область к Git.
2. Клонируйте репозиторий Git в локальную файловую систему.
3. Откройте отчет в Power BI Desktop, открыв definition.pbir файл.
4. Сохраните отчет и выберите обновление до PBIR.
5. Фиксация и синхронизация изменений в Git.
6. Обновите рабочую область с последними изменениями из Git.

Папка и файлы PBIR

Определение отчета хранится в папке со следующей definition\ структурой:

Markdown

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

Важно!

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

Соглашение об именовании PBIR

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

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

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

Схемы JSON PBIR

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

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

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

Заметки PBIR

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

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

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 или внешнего средства, если файл подчиняется схеме JSON. Использование неправильного имени или типа свойства можно легко обнаружить непосредственно в Visual Studio Code:

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

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

Ошибки, такие как недопустимая схема или отсутствующие обязательные свойства, считаются блокирующими ошибками. Эти ошибки можно легко определить, открыв файл в Visual Studio Code и проверяя ошибки схемы.

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

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

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

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

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

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

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

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

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

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

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

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

PBIR в настоящее время находится в предварительной версии. Помните о перечисленных ниже моментах.

• Ограничения и ошибки службы
  • Невозможно развернуть с помощью конвейеров развертывания.
  • Невозможно сохранить как копию.
  • Невозможно использовать API отчетов Power BI: клонирование отчета: обновление содержимого отчета
• Большие отчеты с более чем 500 файлами с проблемами с производительностью разработки (просмотр отчетов не затрагивается), в том числе:
  • Сохранение в Power BI Desktop
  • Синхронизация в интеграции с Fabric Git
• После преобразования отчета из PBIR-Legacy в PBIR невозможно выполнить откат.
• Преобразование PBIP-файла в PBIX-файл с помощью функции "Сохранить как" внедряет отчет PBIR в PBIX-файл, перенося все ограничения PBIR в PBIX.

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

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

Во время общедоступной предварительной версии интерфейсы REST API Fabric иFabric продолжают использовать PBIR-Legacy (report.json) при экспорте определений отчетов. Однако если отчет импортируется в Fabric с помощью формата PBIR, оба компонента начинают экспортировать определение отчета с помощью формата PBIR.

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

• Папка семантической модели проекта Power BI Desktop
• Проекты Power BI Desktop