Поделиться через

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

semanticModelDiagramLayout.json

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

определение.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 Идентификатор удаленной семантической модели.
тип подключения Тип подключения. Для удаленной семантической модели службы это значение должно быть pbiServiceXmlaStyleLive.
pbiModelVirtualServerName Внутреннее свойство должно иметь значение sobe_wowvirtualserver.
pbiServiceModelId Внутреннее свойство должно иметь значение null.
имя Внутреннее свойство должно иметь значение EntityDataSource.

Пример с использованием 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": "[Semantic Model Id]",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": "EntityDataSource"
    }
  }
}

Внимание

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

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

  ├── 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.

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

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

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

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

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

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

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

Перейдите в Файл > Параметры и настройки > Параметры > Предварительные функции и установите флажок рядом с Хранить отчеты в расширенном формате метаданных (PBIR).

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

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

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

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

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

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

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

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

  3. Сохраните проект. Вам будет предложено обновиться до PBIR.

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

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

    Внимание

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

    Power BI Desktop автоматически создает резервную копию отчета перед обновлением до PBIR. Эта резервная копия сохраняется в течение 30 дней в одном из следующих расположений:

    • Версия Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Версия исполняемого установщика: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups

Существующий файл PBIR-Legacy (report.json) заменяется папкой \definition , содержащей представление отчета 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 или внешнего средства, если файл подчиняется схеме 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 в настоящее время находится в предварительной версии. Необходимо учитывать следующие ограничения.

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

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

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

Интеграция Git Fabric и REST API Fabric экспортируют отчеты, используя формат, применяемый в настоящее время в сервисе. Если отчет создается или импортируется в Fabric с помощью формата PBIR, он будет экспортирован в PBIR. Аналогичным образом, если отчет является PBIR-Legacy, он будет экспортирован в формате PBIR-Legacy.

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