Pasta de relatório de projeto do Power BI Desktop

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

1 - Este ficheiro é obrigatório.
2 - Este ficheiro é necessário para o formato PBIR-Legacy.
3 - Este ficheiro é obrigatório para o formato PBIR.

Nem todas as pastas de relatório de projeto incluem todos os arquivos e subpastas descritos aqui.

Ficheiros de relatório

.pbi\localSettings.jsem

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

Para obter mais informações, consulte o localSettings.json documento de esquema.

VisualizaçõesPersonalizadas\

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

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

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

Recursos Registrados\

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

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

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

Cada ficheiro de recurso deve ter uma entrada correspondente no ficheiro report.json. As edições em arquivos RegisteredResources são suportadas apenas para recursos já carregados que fazem com que o Power BI Desktop registre o recurso no report.json.

semanticModelDiagramLayout.json

Contém diagramas de modelo de dados que descrevem a estrutura do modelo semântico associado ao relatório. Este ficheiro não suporta edição externa.

definição.pbir

Contém a definição geral de um relatório e as configurações principais. Esse arquivo também contém a referência ao modelo semântico usado pelo relatório. O Power BI Desktop pode abrir um arquivo PBIR diretamente, da mesma forma como se o relatório fosse aberto a partir de um arquivo PBIP. Abrir um arquivo PBIR também abre o modelo semântico ao lado se houver uma referência relativa usando byPath.

Exemplo de definição.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 datasetReference propriedade, que faz referência ao modelo semântico usado no relatório. A referência pode ser uma das seguintes:

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 pasta. Quando usado, o Power BI Desktop também abre o modelo semântico no modo de edição completa.

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

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

Propriedade Descrição
string de conexão A cadeia de conexão referente 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 de malha, 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 Fabric REST API, deve-se 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 no relatório especifica apenas a qual modelo semântico o relatório se conecta, 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 espaço de trabalho, o Fabric Git Integration sempre exporta definições com uma byPath referência ao modelo semântico. Se quiser forçar a abertura do relatório com conectividade ao vivo (por exemplo, para trabalhar com medidas no nível do relatório), é possível ter vários *.pbir ficheiros, como um com uma conexão byPath e outro com uma conexão 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 suportados por meio da propriedade 'version'.

Versão Formatos suportados
1.0 A definição de relatório deve ser armazenada como PBIR-Legacy no arquivo report.json.
4.0 ou superior A definição de relatório pode ser armazenada como PBIR-Legacy (arquivoreport.json) ou PBIR (pasta \definition).

Para obter mais informações, consulte 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. Este ficheiro não suporta edição externa.

report.json

Este ficheiro contém a definição de relatório no formato Legado de Relatório do Power BI (PBIR-Legado) e não suporta 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 avançado do Power BI (PBIR). Ele substitui o arquivo report.json .

.plataforma

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

Para saber mais, consulte Arquivos de sistema gerados automaticamente pela integração do Git.

Formato PBIR

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

Captura de ecrã de diferenças amigáveis do PBIR.

Cada página, visual, marcador, etc., é organizada em um arquivo separado e individual dentro de uma estrutura de pastas. Este 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 oferece suporte a modificações de aplicativos que não são do Power BI. Cada arquivo tem 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 o PBIR incluem:

  • Copie páginas, visuais, ou marcadores entre relatórios.
  • Garanta a consistência de um conjunto de elementos visuais em todas as páginas, copiando e colando os arquivos visuais.
  • Fácil de encontrar e substituir 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 um projeto usando PBIR

Quando guarda um projeto usando PBIR, o seu relatório é guardado numa 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 de relatório é armazenada dentro da definition\ pasta 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
Ficheiro/Pasta Necessário Descrição
Favoritos\ Não Pasta que contém todos os arquivos de favoritos do relatório.
── [NomeDoMarcador].bookmark.json Não Marque metadados, como visuais de destino e filtros.
Mais informações em esquema.
── bookmarks.json Não Metadados de marcadores, como ordem de favoritos e grupos.
Mais informações em esquema.
páginas\ Sim Pasta que contém todas as páginas do relatório.
── [nomedapágina]\ Sim Uma pasta por página.
──── Visuais\ Não Pasta que contém todos os elementos visuais da página.
────── [visualName]\ Não Uma pasta por elemento visual.
──────── mobile.json Não Metadados visuais do layout para dispositivos móveis, como a posição e a formatação desses dispositivos.
Mais informações em esquema.
─────── visual.json Sim Metadados visuais, como posição e formatação, consulta.
Mais informações em esquema.
──── page.json Sim Metadados de página, como filtros de nível de página e formatação.
Mais informações em esquema.
── pages.json Não Metadados das páginas, como ordem das 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 schema
reportExtensions.json Não Extensões de relatório, como medidas de nível de relatório.
Mais informações em schema
report.json Sim Metadados de relatório, como filtros de nível de relatório e formatação.
Mais informações em schema

Importante

Alguns arquivos de metadados de relatório, como visual.json ou bookmarks.json, podem ser salvos com valores de dados do seu 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 segmentadores, largura de colunas personalizadas de matriz e formatação para séries específicas.

Convenção de nomenclatura 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, elementos visuais e marcadores 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 ecrã da propriedade do nome do PBIR.

Renomear a propriedade 'name' dentro de cada ficheiro JSON é possível, mas pode comprometer as referências externas tanto dentro como 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ífenes.

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

Copiar 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 isso, você pode copiar o nome de qualquer nome de objeto de relatório (incluindo páginas, elementos visuais, marcadores e filtros) diretamente do Power BI para sua área de transferência.

Captura de ecrã de um relatório com uma seta a apontar de um dos elementos visuais para o nome do ficheiro correspondente.

  1. Vá para Opções e configurações > de arquivo > 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 do mouse em objetos de relatório. Só precisa de fazer isto uma vez.

    Captura de ecrã das definições de objetos do 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 ecrã de um relatório de ambiente de trabalho com o nome do objeto de cópia selecionado.

Com o nome do objeto copiado para a área de transferência, é possível inseri-lo facilmente na barra de pesquisa do Windows Explorer ou do Visual Studio Code para localizar ou identificar o nome do objeto dentro da pasta PBIR.

Captura de ecrã da barra de pesquisa com o nome do objeto.

Esquemas PBIR JSON

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

Captura de ecrã da descrição de ajuda do prompt de esquema JSON do PBIR.

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

Todos os esquemas JSON são publicados aqui.

Anotações PBIR

Pode incluir anotações sob a forma de pares nome-valor na definição do 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, poderá 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

Pode editar ficheiros JSON PBIR suportados num editor de código como o Visual Studio Code ou outra ferramenta externa enquanto o projeto permanece aberto no Power BI Desktop. Quando guarda os ficheiros, o Power BI Desktop deteta as alterações e mostra o banner 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 ficheiros PBIR externamente, guarde quaisquer alterações no Power BI Desktop. Se o Power BI Desktop tiver alterações não guardadas quando aplicares as alterações externas, avisa-te que as alterações não guardadas serão sobrescritas. Para o fluxo de trabalho completo e limitações, consulte Editar ficheiros PBIP fora do Power BI Desktop.

Os ficheiros PBIR devem conformar-se aos seus esquemas JSON. O VS Code identifica problemas como um nome de propriedade não suportado ou um tipo de propriedade incorreto:

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

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

Erros de bloqueio impedem o Power BI Desktop de carregar as alterações no relatório. Estes erros identificam o problema e o ficheiro que deve corrigir antes de aplicar novamente as alterações:

Captura de ecrã do erro de bloqueio de prompt PBIR.

Erros como um esquema inválido ou propriedades necessárias em falta são erros de bloqueio. Para identificar estes erros, abra o ficheiro no VS Code e inspecione as mensagens de validação do esquema.

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

Captura de ecrã do erro não bloqueante do prompt PBIR.

Uma configuração inválida activePageName é um exemplo de erro não bloqueante que o Power BI Desktop corrige automaticamente. O aviso dá-lhe a oportunidade de rever a correção antes de guardar o relatório e sobrescrever a definição externa.

Erros comuns do PBIR

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

Solução: Verifique se o nome está em conformidade com a convenção de nomenclatura. Caso contrário, o Power BI Desktop ignora o ficheiro ou pasta e trata-o como ficheiros de utilizador privados.

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

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

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

Solução: Esse comportamento é intencional, os marcadores de relatório capturam o estado de uma página de relatório junto com todos os seus elementos visuais. Como o estado capturado se origina de outra página de relatório com visuais diferentes, todos os elementos visuais inválidos são removidos da configuração do marcador. Caso tu copies também os elementos visuais e a página associados, o marcador manterá a sua 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."

Solução: O objeto pageBinding é necessário para suportar a análise detalhada e as informações sobre ferramentas de página. Como eles podem ser referenciados por outras páginas, o nome deve ser exclusivo dentro do 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 é mais um problema porque o nome pageBinding é um GUID por padrão.

Converter relatório existente em PBIR

O PBIR está geralmente disponível e é o formato padrão de relatório. Ainda podes abrir relatórios que usam PBIR-Legacy no Power BI Desktop e no serviço Power BI. Quando editas e guardas um relatório PBIR-Legacy, Power BI converte-o silenciosamente e automaticamente para PBIR.

Antes da conversão, o Power BI cria uma cópia de segurança do relatório:

  • O Power BI Desktop mantém a cópia de segurança durante 30 dias numa das seguintes localizações:
    • 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 Power BI mantém a cópia de segurança PBIR-Legacy por 28 dias. Para o restaurar, abra as definições de Relatório a partir do espaço de trabalho e selecione Restaurar como PBIR-Legacy. Este backup é criado apenas para relatórios convertidos diretamente no serviço Power BI.

Restaurar uma PBIR-Legacy backup não impede outra conversão. Para manter um relatório no formato PBIR-Legacy, não o edite no serviço Power BI nem utilize uma versão do Power BI Desktop anterior a setembro de 2026.

Considerações e limitações do PBIR

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

  • Os filtros automáticos visuais são mantidos no arquivo PBIR visual.json somente após o painel de filtros ter sido expandido pelo menos uma vez durante a edição do relatório.
  • Se o Power BI não converter um relatório PBIR-Legacy para PBIR quando o editar e guardar, ocorreu um problema no produto durante a conversão. Crie um pedido de apoio para reportar o problema.

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

  • 1.000 páginas máximas por relatório.
  • Máximo de 1000 elementos 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, considere otimizar seu relatório. Consulte o documento de Otimização do Power BI.

As APIs Fabric Git Integration e Fabric REST exportam definições de relatórios usando PBIR.

Conteúdos relacionados

  • Last updated on