Бөлісу құралы:

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

  • Мақала

Внимание

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

semanticModelDiagramLayout.json

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

definition.pbir

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

Пример определения.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": null
    }
  }
}

Если семантическая модель и отчет используют одну и ту же рабочую область, интеграция Fabric Git всегда использует ссылку byPath на семантику модели.

Этот файл также задает поддерживаемые форматы определения отчета с помощью свойства 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Внимание

    После обновления до 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\ структурой:

├── 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 Да Метаданные отчета, такие как фильтры уровня отчета и форматирование.
Дополнительные сведения о схеме

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

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

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

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

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

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

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

Внешние изменения содержимого 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 г. эта ситуация больше не является проблемой, так как имя pageBinding по умолчанию является GUID.

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

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

  • Ограничения службы
    • Мобильные представления не отображаются в Приложениях 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.

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