Carpeta de informes de proyectos de Power BI Desktop

Importante

Los proyectos de Power BI Desktop se encuentran actualmente en versión preliminar.

En este artículo se describen los archivos y las subcarpetas de una carpeta Informe de un proyecto de Microsoft Power BI Desktop. Los archivos y subcarpetas de aquí representan un informe de Power BI. En función del proyecto, la carpeta del informe puede incluir:

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• report.json²
• la carpeta definition\³
• .platform

1 - Este archivo es necesario.
2: este archivo es necesario al guardar en formato PBIR-Legacy.
3: este archivo es necesario al guardar en formato PBIR.

No todas las carpetas del informe del proyecto incluyen todos los archivos y subcarpetas que se describen aquí.

Archivos de informe

.pbi\localSettings.json

Contiene la configuración del informe que solo se aplica al usuario actual y al equipo local. Debe incluirse en gitIgnore u otras exclusiones de control de código fuente. De forma predeterminada, Git omitirá este archivo.

Para obtener más información, consulte el documento de esquema localSettings.json.

CustomVisuals\

Subcarpeta que contiene metadatos para objetos visuales personalizados en el informe. Power BI admite tres tipos de objetos visuales personalizados:

• Objetos visuales de almacén organizativos: las organizaciones pueden aprobar e implementar objetos visuales personalizados en Power BI para su organización. Para más información, consulte Almacén de la organización.
• Objetos visuales de Power BI de AppSource: también conocidos como "objetos visuales personalizados públicos". Estos objetos visuales están disponibles en Microsoft AppSource. Los desarrolladores de informes pueden instalar estos objetos visuales directamente en Power BI Desktop.
• Archivos de objetos visuales personalizados: también conocidos como "objetos visuales personalizados privados". Los archivos se pueden cargar en el informe cargando un paquete pbiviz.

Solo los objetos visuales personalizados privados se cargan en la carpeta CustomVisuals. Los objetos visuales de AppSource y de la organización se cargan automáticamente mediante Power BI Desktop.

RegisteredResources\

Subcarpeta que incluye archivos de recursos específicos del informe y cargados por el usuario, como temas personalizados, imágenes y objetos visuales personalizados (archivos pbiviz).

Los desarrolladores son responsables de los archivos de aquí y se admiten los cambios. Por ejemplo, podría cambiar un archivo y, después de reiniciar Power BI Desktop, el nuevo archivo se cargará en el informe. Esta carpeta puede desbloquear algunos escenarios útiles, como:

• Creación de temas personalizados fuera de Power BI Desktop mediante el esquema público.
• Aplicar cambios por lotes cambiando el archivo de recursos en varios informes. Por ejemplo, podría cambiar el tema personalizado corporativo, cambiar entre temas claros y oscuros, y cambiar imágenes de logotipo.

Cada archivo de recursos deberá tener una entrada correspondiente en el archivo report.json, que durante la versión preliminar no admitirá la edición. Las modificaciones en los archivos RegisteredResources solo se admiten para los recursos ya cargados que hacen que Power BI Desktop registre el recurso en report.json.

semanticModelDiagramLayout.json

Contiene diagramas de modelos de datos que describen la estructura del modelo semántico asociado al informe. Durante la versión preliminar, este archivo no admite la edición externa.

definition.pbir

Contiene la definición general de un informe y la configuración principal. Este archivo también contiene la referencia al modelo semántico utilizado por el informe. Power BI Desktop puede abrir un archivo pbir directamente, igual que si el informe se hubiera abierto desde un archivo pbip. Al abrir un pbir también se abre el modelo semántico junto con si hay una referencia relativa mediante byPath.

Ejemplo de definition.pbir:

{
  "version": "1.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    },
    "byConnection": null
  }
}

La definición incluye la propiedad datasetReference, que hace referencia al modelo semántico usado en el informe. La referencia puede ser:

byPath : especifica una ruta de acceso relativa a la carpeta del modelo semántico de destino. No se admiten rutas de acceso absolutas. Se usa una barra diagonal (/) como separador de carpetas. Cuando se usa, Power BI Desktop también abre el modelo semántico en modo de edición completa.

byConnection : especifica un modelo semántico remoto en el servicio Power BI mediante una cadena de conexión. Cuando se usa una referencia byConnection, Power BI Desktop no abre el modelo semántico en modo de edición.

Con una referencia byConnection, se deberán especificar las siguientes propiedades:

Propiedad	Descripción
connectionString	Cadena de conexión que hace referencia al modelo semántico remoto.
pbiModelDatabaseName	Identificador del modelo semántico remoto.
connectionType	Tipo de conexión. Para el modelo semántico remoto del servicio, este valor debe ser pbiServiceXmlaStyleLive.
pbiModelVirtualServerName	Propiedad interna que debería tener el valor, sobe_wowvirtualserver.

Ejemplo con 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
    }
  }
}

Cuando el modelo semántico y el informe comparten la misma área de trabajo, Fabric Git Integration siempre usa una referencia byPath al modelo semántico.

Este archivo también especifica los formatos de definición de informe admitidos a través de la propiedad 'version'.

Versión	Formatos compatibles
1.0	La definición del informe debe almacenarse como PBIR-Legacy en el archivo report.json.
4.0 o superior	La definición del informe se puede almacenar como PBIR-Legacy (archivo report.json) o PBIR (\definition folder).

Para obtener más información, consulte el documento de esquema definition.pbir.

mobileState.json

Contiene la apariencia del informe y la configuración de comportamiento al representarse en un dispositivo móvil. Este archivo no admite la edición externa.

report.json

Este archivo contiene la definición de informe en el formato heredado de informes de Power BI (PBIR-Legacy) y no admite la edición externa.

Folder definition\

Esta carpeta solo está disponible si el proyecto de Power BI se guarda mediante el formato de informe mejorado de Power BI (PBIR). Reemplaza el archivo report.json.

Luck!

Archivo de plataforma Fabric que contiene propiedades vitales para establecer y mantener la conexión entre elementos de Fabric y Git.

Para más información, vea Integración de Git generada automáticamente de archivos del sistema.

Formato PBIR

Importante

Tenga en cuenta todas las limitaciones PBIR durante la fase de versión preliminar.

Guardar los archivos de proyecto de Power BI (PBIP) mediante el formato de informe mejorado (PBIR) de Power BI mejora considerablemente el seguimiento de cambios y la resolución de conflictos de combinación mediante archivos JSON con el formato correcto.

Cada página, objeto visual, marcador, etc., se organiza en un archivo individual independiente dentro de una estructura de carpetas. Este formato es ideal para la resolución de conflictos de desarrollo conjunta.

A diferencia de PBIR-Legacy (report.json), PBIR es un formato documentado públicamente que admite modificaciones de aplicaciones que no son de Power BI. Cada archivo tiene un esquema JSON público, que no solo documenta el archivo, sino que también permite que los editores de código como Visual Studio Code realicen la validación de sintaxis durante la edición.

Algunos de los posibles escenarios disponibles ahora con PBIR incluyen:

• Copie páginas, objetos visuales o marcadores entre informes.
• Asegúrese de la coherencia de un conjunto de objetos visuales en todas las páginas, copiando y pegando los archivos visuales.
• Búsqueda y sustitución sencillas en varios archivos de informes.
• Aplicación de una edición por lotes en todos los objetos visuales mediante un script (por ejemplo, ocultar filtros de nivel visual)

Habilitación de la característica en vista previa de PBIR

Guardar como un proyecto de Power BI Desktop usando PBIR está actualmente en versión preliminar. Antes de usarla, habilítela en las características de versión preliminar de Power BI Desktop:

Vaya a Archivo > Opciones y configuración > Opciones > Características en vista previa y marque la casilla junto a Almacenar informes mediante el formato de metadatos mejorado (PBIR).

Guardar como un proyecto con el formato PBIR

Con la característica en vista previa PBIR habilitada, al guardar un proyecto, el informe se guarda dentro de una carpeta denominada \definition dentro de la carpeta de informes:

Obtenga más información sobre la estructura de carpetas de PBIR.

Conversión del PBIP existente a PBIR

Si ya tiene un PBIP con el formato PBIR-Legacy, puede convertirlo a PBIR de la siguiente manera:

1. Abra el PBIP en Power BI Desktop.

2. Asegúrese de que la característica en vista previa esté habilitada.

3. Guarde el proyecto. Aparece un mensaje que le pide que actualice a PBIR.

4. Seleccione Actualizar.

   

   Importante

   Una vez que actualice a PBIR, no podrá volver a PBIR-Legacy. Si cree que es posible que desee volver a PBIR-Legacy, guarde primero una copia de los archivos PBIP.

El archivo PBIR-Legacy existente (report.json) se reemplaza por una carpeta \definition que contiene la representación PBIR del informe.

Si selecciona el formato Mantener el actual, Desktop no le pedirá otra vez que actualice.

Publicación de un informe PBIR en el servicio

Aunque en la fase de versión preliminar, la única manera de publicar un informe con el formato PBIR es a través de la integración de Git de Fabric. Esto implica conectar el área de trabajo a un repositorio de Git e insertar el informe PBIR en él, que luego se puede sincronizar con el área de trabajo de servicio en una fase posterior.

Si desea convertir un informe existente en PBIR en el servicio, siga estos pasos:

1. Conecte el área de trabajo a Git.
2. Clone el repositorio de Git en el sistema de archivos local.
3. Abra el informe en Power BI Desktop abriendo el archivo definition.pbir.
4. Guarde el informe y elija actualizar a PBIR.
5. Confirme y sincronice los cambios en Git.
6. Actualice el área de trabajo con los cambios más recientes de Git.

Archivos y carpetas PBIR

La definición del informe se almacena dentro de la carpeta definition\ con la siguiente estructura:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

Archivo o carpeta	Obligatorio	Descripción
bookmarks\	No	Carpeta que contiene todos los archivos de marcador del informe.
── [bookmarkName].bookmark.json	No	Metadatos de marcador, como los objetos visuales de destino y los filtros. Más información en esquema.
── bookmarks.json	No	Metadatos de marcadores, como el orden de los marcadores y los grupos. Más información en esquema.
pages\	Sí	Carpeta que contiene todas las páginas del informe.
── [pageName]\	Sí	Una carpeta por página.
──── visuals\	No	Carpeta que contiene todos los objetos visuales de la página.
────── [visualName]\	No	Una carpeta por objeto visual.
──────── mobile.json	No	Metadatos de diseño de dispositivos móviles visuales, como la posición móvil y el formato. Más información en esquema.
──────── visual.json	Sí	Metadatos visuales, como la posición y el formato, consulta. Más información en esquema.
──── page.json	Sí	Metadatos de página, como filtros de nivel de página y formato. Más información en esquema.
── pages.json	No	Metadatos de páginas, como el orden de página y la página activa. Más información en esquema.
version.json	Sí	La versión del archivo PBIR, entre otros factores, determina los archivos necesarios que se van a cargar. Más información en esquema
reportExtensions.json	No	Extensiones de informe, como medidas de nivel de informe. Más información en esquema
report.json	Sí	Metadatos de informe, como filtros de nivel de informe y formato. Más información en esquema

Convención de nomenclatura de PBIR

Todos los nombres entre corchetes ([]) de la tabla anterior siguen una convención de nomenclatura predeterminada, pero se puede cambiar el nombre a nombres más fáciles de usar. De forma predeterminada, las páginas, los objetos visuales y los marcadores usan su nombre de objeto de informe como nombre de archivo o carpeta. Estos nombres de objeto son inicialmente un identificador único de 20 caracteres, como "90c2e07d8e84e7d5c026".

Se admite el cambio de nombre de la propiedad "name" dentro de cada archivo JSON, pero puede interrumpir las referencias externas tanto dentro como fuera del informe. El nombre del objeto o el nombre de archivo o carpeta debe constar de uno o más caracteres de palabra (letras, dígitos, caracteres de subrayado) o guiones.

Después de cambiar el nombre de los archivos o carpetas PBIR, debe reiniciar Power BI Desktop. Al reiniciarse, Power BI Desktop conservará los nombres de archivo o carpeta originales al guardar.

Esquemas JSON de PBIR

Cada archivo JSON de PBIR incluye una declaración de esquema JSON en la parte superior del documento. Esta dirección URL de esquema es accesible públicamente y se puede usar para obtener más información sobre las propiedades y objetos disponibles para cada archivo. Además, proporciona IntelliSense integrado y validación al editar con editores de código como Visual Studio Code.

La dirección URL del esquema también define la versión del documento, que se espera que cambie a medida que evoluciona la definición del informe.

Todos los esquemas JSON se publican aquí.

Anotaciones PBIR

Puede incluir anotaciones como pares nombre-valor dentro de la definición de informe para cada visualy reportpage . Aunque Power BI Desktop omitirá estas anotaciones, pueden ser útiles para aplicaciones externas como scripts.

Por ejemplo, puede especificar defaultPage para el informe en el report.json archivo, que después puede usar un script de implementación.

{
  "$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"
    }
  ]
}

Cambios externos en archivos PBIR

Puede editar los archivos JSON de PBIR mediante un editor de código como Visual Studio Code o una herramienta externa, siempre y cuando el archivo obedezca el esquema JSON. El uso de un nombre o tipo de propiedad incorrecto se puede detectar fácilmente directamente en Visual Studio Code:

Los cambios externos en el contenido de PBIR pueden producir errores al volver a abrir los archivos en Power BI Desktop. Estos errores pueden ser de dos tipos:

Los errores de bloqueo impiden que Power BI Desktop abra el informe. Estos errores ayudan a identificar el problema y el archivo infractor que se debe corregir antes de volver a abrirlo:

Los errores como un esquema no válido o las propiedades necesarias que faltan se consideran errores de bloqueo. Estos errores se pueden identificar fácilmente abriendo el archivo en Visual Studio Code e inspeccionando los errores de esquema.

Los errores de no bloqueo no impiden que Power BI Desktop abra el informe y se resuelvan automáticamente.

Los errores como una configuración de activePageName no válida son ejemplos de errores de no bloqueo que se corrigen automáticamente. La advertencia es necesaria para darle la oportunidad de evitar guardar el informe con el autofijador, evitando así cualquier posible pérdida de trabajo.

Errores comunes de PBIR

Escenario: Después de cambiar el nombre de los nombres de carpeta visual o de página, mi objeto visual o página ya no aparece al abrir el informe.

Solución: Compruebe si el nombre cumple con la convención de nomenclatura. Si no es así, Power BI Desktop omite el archivo o carpeta y lo trata como archivos de usuario privados.

Escenario: los nuevos objetos de informe se denominan de forma diferente a otros. Por ejemplo, la mayoría de las carpetas de página se denominan "ReportSection0e71dafbc949c0853608", mientras que algunas se denominan "1b3c2ab12b603618070b".

Solución: PBIR adoptó una nueva convención de nomenclatura para cada objeto, pero solo se aplica a los nuevos. Al guardar un informe existente como PBIP, los nombres actuales deben conservarse para evitar referencias importantes. Si desea mantener la coherencia, se permite un cambio de nombre de lote en un script.

Escenario: he copiado un archivo de marcador y, tras guardar, se eliminó la mayoría de la configuración del marcador.

Solución: este comportamiento es intencionado, los marcadores de informe capturan el estado de una página de informe junto con todos sus objetos visuales. Dado que el estado capturado procede de otra página de informe con objetos visuales diferentes, los objetos visuales no válidos se eliminan de la configuración del marcador. Si también copia los objetos visuales y la página dependientes, el marcador mantendrá su configuración.

Escenario: he copiado una carpeta de páginas de otro informe y he encontrado un error que indica que "Los valores de la propiedad "pageBinding.name" deben ser únicos".

Solución: ek objeto pageBinding es necesario para admitir la obtención de detalles y la información sobre herramientas de página. Dado que otras páginas pueden hacer referencia a ellas, el nombre debe ser único dentro del informe. En la página recién copiada, asigne un valor único para resolver el error. Después de junio de 2024, esta situación ya no es un problema porque el nombre pageBinding es un GUID de forma predeterminada.

Consideraciones y limitaciones de PBIR

PBIR se encuentra actualmente en versión preliminar. Tenga en cuenta lo siguiente:

• Limitaciones del servicio
  • Las vistas móviles no se muestran en Aplicaciones de Power BI.
  • No se puede implementar con canalizaciones de implementación.
  • No se puede guardar como copia.
• Los informes grandes con más de 500 archivos experimentan problemas de rendimiento en la creación (la visualización del informe no se ve afectado), lo que incluye:
  • Guardado en Power BI Desktop
  • Sincronización en la integración de Git de Fabric
• Una vez que un informe se convierte de PBIR-Legacy a PBIR, no es posible revertirlo.
• La conversión de un archivo PBIP en un archivo PBIX mediante la característica "Guardar como" inserta el informe PBIR dentro del archivo PBIX, llevando todas las limitaciones de PBIR al PBIX.

Limitaciones de tamaño de PBIR aplicadas por el servicio:

• 1000 páginas máximas por informe.
• 300 objetos visuales máximos por página.
• 5 mb máximo para cada archivo de marcador.
• 1 mb máximo para cada archivo.
• 1000 archivos de paquetes de recursos como máximo por informe.
• Tamaño máximo de 300 mb para todos los archivos de paquete de recursos.
• Tamaño máximo de 20 mb de todos los archivos de informe.

Durante la versión preliminar pública, Fabric Git Integration y API de REST de Fabric siguen usando PBIR-Legacy (report.json) al exportar las definiciones de informe. Sin embargo, si el informe se importa en Fabric mediante el formato PBIR, ambas características comienzan a exportar la definición de informe mediante el formato PBIR.

Contenido relacionado

• Carpeta del modelo semántico del proyecto de Power BI Desktop
• Proyectos de Power BI Desktop