Carpeta de informes de proyectos de Power BI Desktop

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:

1 - Este archivo es necesario.
2 - Este archivo es necesario para PBIR-Legacy formato.
3 - Este archivo es necesario para el 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.jsencendido

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 debe tener una entrada correspondiente en el archivo report.json. 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. Este archivo no admite la edición externa.

definición.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 abrió desde un archivo PBIP. Al abrir un archivo PBIR, también se abre el modelo semántico si hay una referencia relativa usando byPath.

Definición de ejemplo.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"
    }    
  }
}

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 la conexión a un modelo semántico en un área de trabajo de Fabric 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 en un área de trabajo de Fabric.

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

Al implementar un informe a través de la API REST de Fabric, solo tiene que especificar la semanticmodelid propiedad . Por ejemplo:

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

Importante

Al implementar un informe mediante API de REST de Fabric, debe usar referencias de byConnection. Esto no debe confundirse con el modo de almacenamiento de un modelo semántico, como DirectQuery. En datasetReference el informe solo se especifica a qué modelo semántico se conecta el informe, no define cómo almacena o accede a sus datos.

Varios archivos *.pbir

Cuando el modelo semántico y el informe comparten el mismo área de trabajo, Fabric Git Integration siempre exporta definiciones con una byPath referencia al modelo semántico. Si desea forzar que el informe se abra en conexión en tiempo real, por ejemplo, para trabajar con medidas a nivel de informe, puede tener varios *.pbir archivos, como uno con una conexión byPath y otro con una conexión byConnection. Fabric Git Integration procesa solo el archivo definition.pbir y omite todos los demás archivos *.pbir. Sin embargo, estos archivos pueden coexistir en el mismo repositorio.

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

El definition.pbir 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.

definición\ carpeta

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.

.plataforma

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

Para obtener más información, consulte Archivos del sistema generados automáticamente por la integración de Git.

Formato PBIR

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.

Recorte de pantalla de las diferencias de PBIR amigables.

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 codesarrollo.

Captura de pantalla de la carpeta PBIR amigable.

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)

Guardar como un proyecto con el formato PBIR

Al guardar un proyecto mediante PBIR, el informe se guarda dentro de una carpeta denominada \definition dentro de la carpeta del informe:

Captura de pantalla de la carpeta de definición dentro de una carpeta PBIP de informe.

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

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
marcadores No Carpeta que contiene todos los archivos de marcadores del informe.
── [nombreDeMarcador].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.
páginas\ Sí Carpeta que contiene todas las páginas del informe.
── [nombreDePágina]\ Sí Una carpeta por página.
──── objetos visuales\ No Carpeta que contiene todos los elementos visuales de la página.
────── [nombreDeObjetoVisual]\ 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

Importante

Algunos archivos de metadatos de informe, como visual.json o bookmarks.json, se pueden guardar con valores de datos del modelo semántico. Por ejemplo, si aplica un filtro a un objeto visual para el campo "Company" = "Contoso", el valor "Contoso" se conservará como parte de los metadatos. Esto también se aplica a otras configuraciones, como selecciones del segmentador, ancho de columnas personalizadas de matriz y formato para series específicas.

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".

Recorte de pantalla de la propiedad nombre de PBIR.

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.

Copiar el nombre del objeto de informe

Cada objeto del informe se guarda en una carpeta o archivo independiente, pero el nombre de la carpeta no siempre es obvio. Para facilitar este proceso, puede copiar el nombre de cualquier nombre de objeto de informe (incluidas páginas, objetos visuales, marcadores y filtros) directamente desde Power BI al Portapapeles.

Captura de pantalla de un informe con una flecha que apunta desde uno de los objetos visuales al nombre de su archivo correspondiente.

  1. Vaya a Opciones y configuración de Archivo >, > Configuración del informe > Objetos de informe y habilite la configuración Copiar los nombres de objeto al hacer clic con el botón derecho en los objetos de informe . Esto solo debe hacerse una vez.

    Captura de pantalla de la configuración del informe de objetos de informe.

  2. Haga clic con el botón derecho en cualquier objeto de informe y seleccione Copiar nombre de objeto.

    Captura de pantalla de un informe de escritorio con el nombre del objeto de copia seleccionado.

Con el nombre de objeto copiado en el Portapapeles, puede escribirlo fácilmente en la barra de búsqueda del Explorador de Windows o Visual Studio Code para buscar o identificar el nombre del objeto dentro de la carpeta PBIR.

Captura de pantalla de la barra de búsqueda con el nombre del objeto.

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.

Recorte de pantalla del aviso de la información sobre herramientas del esquema JSON de PBIR.

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 del informe para cada instancia de visual, page y report. Aunque Power BI Desktop omite estas anotaciones, pueden ser útiles para aplicaciones externas como scripts.

Por ejemplo, puede especificar defaultPage para el informe en el archivo report.json, que luego puede ser utilizado por 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 archivos JSON PBIR compatibles en un editor de código como Visual Studio Code u otra herramienta externa mientras el proyecto permanece abierto en Power BI Desktop. Al guardar los archivos, Power BI Desktop detecta los cambios y muestra el banner Aplicar cambios externos. Seleccione Aplicar cambios externos para volver a cargar la definición del informe sin cerrar y volver a abrir el proyecto.

Antes de editar archivos PBIR externamente, guarde los cambios en Power BI Escritorio. Si Power BI Desktop tiene cambios no guardados al aplicar los cambios externos, le advierte de que los cambios no guardados se sobrescribirán. Para obtener el flujo de trabajo completo y las limitaciones, consulte Editar archivos PBIP fuera de Power BI Desktop.

Los archivos PBIR deben ajustarse a sus esquemas JSON. VS Code identifica problemas como un nombre de propiedad no admitido o un tipo de propiedad incorrecto:

Captura de pantalla de la solicitud de validación del esquema JSON de PBIR.

Los cambios externos en el contenido de PBIR pueden producir errores al aplicar los cambios o abrir los archivos en Power BI Escritorio. Estos errores pueden ser de dos tipos:

Los errores de bloqueo impiden que Power BI Desktop cargue los cambios del informe. Estos errores identifican el problema y el archivo que debe corregir antes de volver a aplicar los cambios:

Captura de pantalla del mensaje de error de bloqueo de PBIR.

Los errores, como un esquema no válido o las propiedades necesarias que faltan, bloquean los errores. Para identificar estos errores, abra el archivo en VS Code e inspeccione los mensajes de validación de esquema.

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

Recorte de pantalla del aviso de error de no bloqueo de PBIR.

Una configuración activePageName no válida es un ejemplo de un error no bloqueante que Power BI Desktop corrige automáticamente. La advertencia le ofrece la oportunidad de revisar la corrección antes de guardar el informe y sobrescribir la definición externa.

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 quiere 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 dependientes y la página, 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: El 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.

Conversión de un informe existente en PBIR

PBIR está disponible con carácter general y es el formato de informe predeterminado. Todavía puede abrir informes que usan PBIR-Legacy en Power BI Desktop y el servicio Power BI. Al editar y guardar un informe de PBIR-Legacy, Power BI lo convierte de forma silenciosa y automática en PBIR.

Antes de la conversión, Power BI crea una copia de seguridad del informe:

  • Power BI Desktop conserva la copia de seguridad durante 30 días en una de las siguientes ubicaciones:
    • Versión de Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Versión del instalador ejecutable: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • El servicio Power BI conserva la copia de seguridad de PBIR-Legacy durante 28 días. Para restaurarlo, abra Configuración de informe desde el área de trabajo y seleccione Restaurar como PBIR-Legacy. Esta copia de seguridad solo se crea para los informes convertidos directamente en el servicio Power BI.

Restaurar una copia de seguridad de PBIR-Legacy no impide otra conversión. Para mantener un informe en formato PBIR-Legacy, no lo edite en el servicio Power BI ni use una versión de Power BI Desktop publicada antes de septiembre de 2026.

Consideraciones y limitaciones de PBIR

Tenga en cuenta las siguientes consideraciones y limitaciones:

  • Los filtros automáticos visuales se conservan en el archivo PBIR visual.json solo después de que el panel de filtros se haya expandido al menos una vez al editar el informe.
  • Si Power BI no convierte un informe de PBIR-Legacy en PBIR al editarlo y guardarlo, la conversión ha encontrado un problema de producto. Cree una solicitud de soporte técnico para notificar el problema.

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

  • 1000 páginas máximas por informe.
  • Un máximo de 1000 objetos visuales por página.
  • 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 300 mb de todos los archivos de informe.

Importante

Si alcanza los límites anteriores, debe considerar la posibilidad de optimizar el informe. Consulte el documento Optimización de Power BI.

la integración de Git de Fabric y las API REST de Fabric exportan definiciones de informes en formato PBIR.

Contenido relacionado

  • Last updated on