Pasta de relatórios do projeto do Power BI Desktop

Este artigo descreve os arquivos e subpastas na pasta Relatório de um projeto do Microsoft Power BI Desktop. Os arquivos e subpastas aqui representam um relatório do Power BI. Dependendo do projeto, a pasta de relatório pode incluir:

1 – este arquivo é necessário.
2 – Esse arquivo é necessário para PBIR-Legacy formato.
3 – Esse arquivo é necessário para o formato PBIR.

Nem toda pasta de relatório de projeto inclui todos os arquivos e subpastas descritos aqui.

Arquivos de relatório

.pbi\localSettings.jsativado

Contém configurações de relatório que se aplicam somente ao usuário atual e ao computador local. Deve ser incluído no gitIgnore ou em outras exclusões de controle do código-fonte. Por padrão, o Git ignora esse arquivo.

Para obter mais informações, confira o documento do esquema localSettings.json.

CustomVisuals\

Uma subpasta que contém metadados para elementos visuais personalizados no relatório. O Power BI dá suporte a três tipos de visuais personalizados:

  • Visuais de repositório organizacional – As organizações podem aprovar e implantar visuais personalizados no Power BI da organização. Para saber mais, veja Loja da organização.
  • Visuais Power BI do AppSource – também conhecidos como "Visuais públicos personalizados". Esses visuais estão disponíveis no Microsoft AppSource. Os desenvolvedores de relatórios podem instalar esses visuais diretamente do Power BI Desktop.
  • Arquivos visuais personalizados – também conhecidos como "Visuais personalizados privados". Os arquivos podem ser carregados no relatório fazendo o upload de um pacote pbiviz.

Somente visuais personalizados privados são carregados na pasta CustomVisuals. Os visuais do AppSource e da Organização são carregados automaticamente pelo Power BI Desktop.

RegisteredResources\

Uma subpasta que inclui arquivos de recursos específicos para o relatório e são carregados pelo usuário, como temas personalizados, imagens e visuais personalizados (arquivos pbiviz).

Os desenvolvedores são responsáveis pelos arquivos aqui e há suporte para alterações. Por exemplo, você pode alterar um arquivo e, após a reinicialização do Power BI Desktop, o novo arquivo é carregado no relatório. Essa pasta pode desbloquear alguns cenários úteis, como:

  • Criar temas personalizados fora do Power BI Desktop usando o esquema público.
  • Aplicar alterações em lote, alterando o arquivo de recurso em vários relatórios. Por exemplo, você pode mudar o tema corporativo personalizado, alternar entre temas claros e escuros e alterar imagens de logotipo.

Cada arquivo de recurso deve ter uma entrada correspondente no arquivo report.json. Só há suporte para edições em arquivos RegisteredResources para recursos que já foram carregados e fazem com que o Power BI Desktop registre o recurso em report.json.

semanticModelDiagramLayout.json

Contém diagramas de modelo de dados que descrevem a estrutura do modelo semântico associado ao relatório. Esse arquivo não dá suporte à edição externa.

definition.pbir

Contém a definição geral de um relatório e configurações básicas. Esse arquivo também contém a referência ao modelo semântico utilizado pelo relatório. O Power BI Desktop pode abrir um arquivo PBIR diretamente, exatamente como se o relatório tivesse sido aberto de um arquivo PBIP. Abrir um arquivo PBIR também abrirá o modelo semântico ao lado se houver uma referência relativa usando byPath.

Exemplo de definition.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"
    }    
  }
}

A definição inclui a propriedade datasetReference, que faz referência ao modelo semântico utilizado no relatório. A referência pode ser uma das duas opções:

byPath - Especifica um caminho relativo para a pasta do modelo semântico de destino. Não há suporte para caminhos absolutos. Uma barra "/" é usada como separador de pastas. Quando usado, o Power BI Desktop também abre o modelo semântico no modo de edição completo.

byConnection – Especifica a conexão com um modelo semântico em um workspace do Fabric usando uma cadeia de conexão. Quando uma referência byConnection é usada, o Power BI Desktop não abre o modelo semântico no modo de edição.

Usando uma referência byConnection, as seguintes propriedades devem ser especificadas:

Propriedade Descrição
string de conexão A cadeia de conexão que faz referência ao modelo semântico em um workspace do Fabric.

Exemplo usando 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]"
    }
  }
}

Ao implantar um relatório por meio da API REST do Fabric, você só precisa especificar a semanticmodelid propriedade. Por exemplo:

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

Ao implantar um relatório por meio da API REST do Fabric, é necessário usar byConnection referências. Isso não deve ser confundido com o modo de armazenamento de um modelo semântico, como o DirectQuery. O datasetReference relatório especifica apenas a qual modelo semântico o relatório se conecta, ele não define como esse modelo armazena ou acessa seus dados.

Vários arquivos *.pbir

Quando o modelo semântico e o relatório compartilham o mesmo workspace, o Fabric Git Integration sempre exporta definições com uma byPath referência ao modelo semântico. Se você quiser forçar o relatório a abrir em live connect (por exemplo, para trabalhar com medidas de nível de relatório), poderá ter vários arquivos *.pbir, como um com uma conexão por 'byPath' e outro com uma conexão por 'byConnection'. O Fabric Git Integration processa apenas o arquivo definition.pbir e ignora todos os outros arquivos *.pbir. No entanto, esses arquivos podem coexistir no mesmo repositório.

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

O definition.pbir arquivo também especifica os formatos de definição de relatório com suporte por meio da propriedade 'version'.

Versão Formatos com suporte
1,0 A definição do relatório deve ser armazenada como PBIR-Legacy no arquivo report.json.
4.0 ou superior A definição do relatório pode ser armazenada como PBIR-Legacy (arquivo report.json) ou PBIR (\pasta definição).

Para obter mais informações, veja o documento de esquema definition.pbir.

mobileState.json

Contém configurações de aparência e comportamento do relatório ao renderizar em um dispositivo móvel. Esse arquivo não dá suporte à edição externa.

report.json

Esse arquivo contém a definição de relatório no formato Power BI Report Legacy (PBIR-Legacy) e não dá suporte à edição externa.

definição\ pasta

Essa pasta só estará disponível se o projeto do Power BI for salvo usando o formato de relatório aprimorado do Power BI (PBIR). Ele substitui o arquivo report.json.

.plataforma

Arquivo da plataforma do Fabric que contém propriedades vitais para estabelecer e manter a conexão entre os itens do Fabric e o Git.

Para saber mais, consulte a Integração do Git com arquivos de sistema gerados automaticamente.

Formato PBIR

Salvar seus arquivos de projeto do Power BI (PBIP) usando o Power BI Enhanced Report Format (PBIR) melhora muito o controle de alterações e a resolução de conflitos de mesclagem usando arquivos JSON formatados corretamente.

Captura de tela de comparações de PBIR amigáveis.

Cada página, visual, marcador, etc., é organizado em um arquivo individual separado dentro de uma estrutura de pastas. Esse formato é ideal para a resolução de conflitos de codesenvolvimento.

Captura de tela da pasta PBIR amigável.

Ao contrário do PBIR-Legacy (report.json), o PBIR é um formato documentado publicamente que dá suporte a modificações de aplicativos que não são do Power BI. Cada arquivo possui um esquema JSON público, que não apenas documenta o arquivo, mas também permite que editores de código como o Visual Studio Code executem a validação de sintaxe durante a edição.

Alguns dos cenários possíveis agora disponíveis com PBIR incluem:

  • Copie páginas, visuais e marcadores entre relatórios.
  • Garanta a consistência de um conjunto de recursos visuais em todas as páginas, copiando e colando os arquivos visuais.
  • Fácil localização e substituição em vários arquivos de relatórios.
  • Aplicar uma edição em lote em todos os elementos visuais usando um script (por exemplo, ocultar filtros de nível visual)

Salvar como projeto usando PBIR

Quando você salva um projeto usando o PBIR, o relatório é salvo em uma pasta chamada \definition dentro da pasta de relatório:

Captura de tela da pasta de definição dentro de uma pasta PBIP de relatório.

Saiba mais sobre a estrutura de pastas PBIR.

Pasta e arquivos PBIR

A definição do relatório é armazenada dentro da pasta definition\ com a seguinte estrutura:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json
Arquivo/pasta Obrigatório Descrição
indicadores\ Não Pasta que contém todos os arquivos de favoritos do relatório.
── [bookmarkName].bookmark.json Não Marque metadados, como recursos visuais e filtros de destino.
Mais informações em esquema.
── bookmarks.json Não Metadados de marcadores, como ordem e grupos de marcadores.
Mais informações em esquema.
páginas\ Sim Pasta contendo todas as páginas do relatório.
── [pageName]\ Sim Uma pasta por página.
──── visuais\ Não Pasta contendo todos os recursos visuais da página.
────── [visualName]\ Não Uma pasta por elemento visual.
──────── mobile.json Não Metadados visuais de layout móvel, como posição e formatação do celular.
Mais informações em esquema.
─────── visual.json Sim Metadados do visual, como posição, formatação e consulta.
Mais informações em esquema.
──── page.json Sim Metadados da página, como filtros e formatação no nível da página.
Mais informações em esquema.
── pages.json Não Metadados de páginas, como ordem de páginas e página ativa.
Mais informações em esquema.
version.json Sim A versão do arquivo PBIR, entre outros fatores, determina os arquivos necessários a serem carregados.
Mais informações em esquema
reportExtensions.json Não Extensões de relatório, como medidas em nível de relatório.
Mais informações em esquema
report.json Sim Metadados de relatório, como filtros e formatação em nível de relatório.
Mais informações em esquema

Importante

Alguns arquivos de metadados de relatório, como visual.json ou bookmarks.json, podem ser salvos com valores de dados do modelo semântico. Por exemplo, se você aplicar um filtro a um visual para o campo 'Empresa' = 'Contoso', o valor 'Contoso' persistirá como parte dos metadados. Isso também se aplica a outras configurações, como seleções de fatiador, largura de colunas personalizadas em matrizes e formatação para séries específicas.

Convenção de nomenclatura do PBIR

Todos os nomes dentro dos colchetes ([]) na tabela anterior seguem uma convenção de nomenclatura padrão, mas podem ser renomeados para nomes mais amigáveis. Por padrão, páginas, visuais e indicadores usam o nome do objeto de relatório como nome de arquivo ou pasta. Esses nomes de objeto são inicialmente um identificador exclusivo de 20 caracteres, como '90c2e07d8e84e7d5c026'.

Captura de tela da propriedade do nome do PBIR.

Há suporte para renomear a propriedade 'name' em cada arquivo JSON, mas pode quebrar referências externas dentro e fora do relatório. O nome do objeto e/ou nome do arquivo/pasta deve consistir em um ou mais caracteres de palavra (letras, dígitos, sublinhados) ou hífens.

Depois de renomear todos os arquivos ou pastas PBIR, você deve reiniciar o Power BI Desktop. Após a reinicialização, o Power BI Desktop preservará os nomes originais de arquivos ou pastas ao salvar.

Copiar o nome do objeto de relatório

Cada objeto no relatório é salvo em uma pasta ou arquivo separado, mas o nome da pasta nem sempre é óbvio. Para facilitar, você pode copiar o nome de qualquer nome de objeto de relatório (incluindo páginas, visuais, indicadores e filtros) diretamente do Power BI para a área de transferência.

Captura de tela de um relatório com uma seta apontando de um dos visuais para o nome de seu arquivo correspondente.

  1. Vá para Arquivo > Opções e configurações > Configurações de relatório > Objetos de relatório e habilite a configuração Copiar nomes de objetos ao clicar com o botão direito nos objetos do relatório. Isso só precisa ser feito uma vez.

    Captura de tela das configurações dos objetos de relatório.

  2. Clique com o botão direito do mouse em qualquer objeto de relatório e selecione Copiar nome do objeto.

    Captura de tela de um relatório da área de trabalho com o nome do objeto de cópia selecionado.

Com o nome do objeto copiado para a área de transferência, você pode inseri-lo com facilidade na barra de pesquisa do Windows Explorer ou do Visual Studio Code para localizar ou identificar o nome do objeto na pasta do PBIR.

Captura de tela da barra de pesquisa com o nome do objeto.

Esquemas JSON do PBIR

Cada arquivo JSON PBIR inclui uma declaração de esquema JSON na parte superior do documento. Esse URL de esquema é acessível publicamente e pode ser usado para saber mais sobre as propriedades e objetos disponíveis para cada arquivo. Além disso, fornece IntelliSense integrado e validação ao editar com editores de código como Visual Studio Code.

Captura de tela da dica de ferramenta do esquema JSON do PBIR.

A URL do esquema também define a versão do documento, que deverá mudar à medida que a definição do relatório evolui.

Todos os esquemas JSON são publicados aqui.

Anotações do PBIR

Você pode incluir anotações como pares nome-valor dentro da definição de relatório para cada visual, page e report. Embora o Power BI Desktop ignore essas anotações, elas podem ser valiosas para aplicativos externos, como scripts.

Por exemplo, você pode especificar a página padrão para o relatório no arquivo report.json, que pode ser utilizado por um script de implantação.

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

Alterações externas em arquivos PBIR

Você pode editar arquivos JSON PBIR com suporte em um editor de código como Visual Studio Code ou outra ferramenta externa enquanto o projeto permanece aberto no Power BI Desktop. Quando você salva os arquivos, o Power BI Desktop detecta as alterações e exibe a faixa Aplicar alterações externas. Selecione Aplicar alterações externas para recarregar a definição do relatório sem fechar e reabrir o projeto.

Antes de editar arquivos PBIR externamente, salve as alterações no Power BI Desktop. Se Power BI Desktop tiver alterações não salvas quando você aplicar as alterações externas, ele avisará que as alterações não salvas serão substituídas. Para obter o fluxo de trabalho completo e as limitações, consulte Editar arquivos PBIP fora do Power BI Desktop.

Os arquivos PBIR devem estar em conformidade com seus esquemas JSON. O VS Code identifica problemas como um nome de propriedade sem suporte ou um tipo de propriedade incorreto:

Captura de tela da validação imediata do esquema JSON PBIR.

Alterações externas no conteúdo do PBIR podem resultar em erros ao aplicar as alterações ou abrir os arquivos no Power BI Desktop. Esses erros podem ser de dois tipos:

Erros de bloqueio impedem que o Power BI Desktop carregue as alterações do relatório. Esses erros identificam o problema e o arquivo que você deve corrigir antes de aplicar as alterações novamente:

Captura de tela do aviso de erro de bloqueio do PBIR.

Erros como um esquema inválido ou propriedades necessárias ausentes estão bloqueando erros. Para identificar esses erros, abra o arquivo no VS Code e inspecione as mensagens de validação de esquema.

Erros sem bloqueio não impedem que o Power BI Desktop abra o relatório e são resolvidos automaticamente.

Captura de tela do aviso de erro sem bloqueio do PBIR.

Uma configuração inválida de activePageName é um exemplo de erro não bloqueante que o Power BI Desktop corrige automaticamente. O aviso oferece a oportunidade de examinar a correção antes de salvar o relatório e substituir a definição externa.

Erros comuns de PBIR

Cenário:depois de renomear nomes de pasta de visual ou página, meu visual ou página não aparece mais ao abrir o relatório.

Solução: Verifique se o nome está de acordo com a convenção de nomenclatura*. Caso contrário, o Power BI Desktop ignora o arquivo ou pasta e o trata como arquivos privados do usuário.

Cenário:novos objetos de relatório são nomeados de forma diferente dos outros. Por exemplo, a maioria das pastas de página é chamada de 'ReportSection0e71dafbc949c0853608', enquanto algumas são nomeadas de '1b3c2ab12b603618070b'.

Solução: O PBIR adotou uma nova convenção de nomenclatura para cada objeto, mas ela só se aplica a novos objetos. Ao salvar um relatório existente como PBIP, os nomes atuais deverão ser preservados para evitar quebras de referências. Se você deseja obter consistência, um script com renomeação em lote é permitido.

Cenário:Copiei um arquivo de indicador e, ao salvar, a maior parte da configuração do indicador foi excluída.

Solução: Esse comportamento é intencional, os marcadores de relatório capturam o estado de uma página de relatório juntamente com todos os seus elementos visuais. Como o estado capturado se origina de outra página de relatório com elementos visuais diferentes, quaisquer elementos visuais inválidos serão removidos da configuração do marcador. Se você também copiar os visuais e a página dependentes, o indicador manterá a configuração.

Cenário:Copiei uma pasta de páginas de outro relatório e encontrei um erro informando: "Os valores da propriedade 'pageBinding.name' devem ser exclusivos."

Cenário: o objeto pageBinding é necessário para dar suporte ao detalhamento e às dicas de ferramentas de página. Como podem ser referenciados por outras páginas, o nome deve ser exclusivo no relatório. Na página recém-copiada, atribua um valor exclusivo para resolver o erro. Após junho de 2024, essa situação não será mais um problema porque o nome pageBinding é um GUID por padrão.

Converter o relatório existente em PBIR

O PBIR está disponível em geral e é o formato de relatório padrão. Você ainda pode abrir relatórios que usam PBIR-Legacy no Power BI Desktop e no serviço do Power BI. Quando você edita e salva um relatório PBIR-Legacy, Power BI silenciosamente e automaticamente o converte em PBIR.

Antes da conversão, Power BI cria um backup do relatório:

  • Power BI Desktop mantém o backup por 30 dias em um dos seguintes locais:
    • Versão da Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Versão do instalador executável: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • O serviço do Power BI mantém o backup PBIR-Legacy por 28 dias. Para restaurá-lo, abra as configurações de relatório do workspace e selecione Restaurar como PBIR-Legacy. Esse backup é criado apenas para relatórios convertidos diretamente no serviço do Power BI.

Restaurar um backup de PBIR-Legacy não impede outra conversão. Para manter um relatório no formato PBIR-Legacy, não edite-o no serviço do Power BI ou use uma versão do Power BI Desktop lançada antes de setembro de 2026.

Considerações e limitações do PBIR

Tenha em mente as seguintes considerações e limitações:

Limitações de tamanho PBIR impostas pelo serviço:

  • Máximo de 1.000 páginas por relatório.
  • Máximo de 1000 visuais por página.
  • Máximo de 1.000 arquivos de pacote de recursos por relatório.
  • Tamanho máximo de 300 mb para todos os arquivos do pacote de recursos.
  • Tamanho máximo de 300 mb de todos os arquivos de relatório.

Importante

Se você atingir os limites acima, deverá considerar a otimização do relatório. Consulte o documento de Otimização do Power BI.

Integração do Git do Fabric e as APIs REST do Fabric exportam definições de relatórios usando PBIR.

Conteúdo relacionado

  • Last updated on