Pasta do relatório do projeto do Power BI Desktop

Importante

Os projetos do Power BI Desktop estão atualmente em versão prévia.

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:

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• report.json²
• definição\ pasta³
• .platform

1 – este arquivo é necessário.
2 - Esse arquivo é necessário ao salvar no formato PBIR-Legacy.
3 - Esse arquivo é necessário ao salvar no formato PBIR.

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

Arquivos de relatório

.pbi\localSettings.json

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 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, confira o tópico Repositório 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, que, durante a versão preliminar, não tem suporte para edição. 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. Durante versão prévia, este arquivo não tem suporte para 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, como se o relatório fosse aberto por um arquivo pbip. Abrir um pbir também abre o modelo semântico ao lado se houver uma referência relativa usando byPath.

Exemplo de definition.pbir:

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

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

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 um modelo semântico remoto no serviço Power BI 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
connectionString	A cadeia de conexão referente ao modelo semântico remoto.
pbiModelDatabaseName	A ID do modelo semântico remoto.
connectionType	Tipo de conexão. Para modelo semântico remoto de serviço, esse valor deve ser pbiServiceXmlaStyleLive.
pbiModelVirtualServerName	Uma propriedade interna que deve ter o valor, sobe_wowvirtualserver.

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

Quando o modelo semântico e o relatório compartilham o mesmo espaço de trabalho, Fabric Git Integration sempre usa uma byPath referência ao modelo semântico.

Esse arquivo também especifica os formatos de definição de relatório suportados através da propriedade 'versão'.

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 definição.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.

Mail Luck!.

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

Importante

Considere todas as limitações do PBIR durante a fase de visualização.

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.

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

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/recursos visuais/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)

Habilitar versão prévia do recurso no formato PBIR

Salvar como um projeto do Power BI usando PBIR está atualmente em versão prévia. Antes de usá-lo, habilite-o nos recursos de visualização do Power BI Desktop:

Vá para Arquivo > Opções e configurações > Opções > Recursos de visualização e marque a caixa ao lado de Armazenar relatórios usando formato de metadados aprimorado (PBIR).

Salvar como projeto usando PBIR

Com a Versão prévia do recurso PBIR habilitado, quando você salva um projeto, seu relatório é salvo em uma pasta chamada \definição dentro da pasta do relatório:

Saiba mais sobre a estrutura de pastas PBIR.

Converter PBIP existente em PBIR

Se você já possui um PBIP usando o formato PBIR-Legacy, poderá convertê-lo para PBIR da seguinte maneira:

1. Abra o PBIP no Power BI Desktop.

2. Certifique-se de que a versão prévia do recurso esteja habilitada.

3. Salvaro projeto. Um prompt aparece solicitando que você atualize para o PBIR.

4. Selecione Atualizar.

   

   Importante

   Depois de atualizar para o PBIR, você não poderá reverter para o PBIR-Legacy. Se você acha que deseja voltar ao PBIR-Legacy, salve primeiro uma cópia dos seus arquivos PBIP.

O arquivo PBIR-Legacy existente (report.json) é substituído por uma pasta \definição contendo a representação PBIR do relatório.

Se você selecionar Manter o formato atual, o Desktop não solicitará novamente a atualização.

Publicar um relatório PBIR para serviço

Ainda na fase de versão prévia, a única forma de publicar um relatório no formato PBIR é por meio do Fabric Git Integration. Isso envolve conectar o espaço de trabalho a um repositório Git e enviar o relatório PBIR para ele, que pode então ser sincronizado com o espaço de trabalho do serviço posteriormente.

Se desejar converter um relatório existente em PBIR no serviço, siga essas etapas:

1. Conecte seu espaço de trabalho ao Git.
2. Clone o repositório Git em seu sistema de arquivos local.
3. Abra o relatório no Power BI Desktop abrindo o arquivo definition.pbir.
4. Salve o relatório e opte por atualizar para PBIR.
5. Confirme e sincronize as alterações com o Git.
6. Atualize o espaço de trabalho com as alterações mais recentes do Git.

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
bookmarks\	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 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 visuais, como posição e formatação, consultam. 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

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, 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'.

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.

Esquemas Json 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.

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 PBIR

Você pode incluir anotações como pares nome-valor na 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 o defaultPage para o relatório no report.json arquivo, 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 os arquivos JSON PBIR usando um editor de código como o Visual Studio Code ou uma ferramenta externa, desde que o arquivo obedeça ao esquema JSON. O uso de um nome ou tipo de propriedade incorreto pode ser facilmente detectado diretamente no Visual Studio Code:

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

Erros de bloqueio impedem que o Power BI Desktop abra o relatório. Esses erros ajudam a identificar o problema e o arquivo incorreto que deve ser corrigido antes da reabertura:

Erros como esquema inválido ou propriedades obrigatórias ausentes são considerados erros de bloqueio. Esses erros podem ser facilmente identificados abrindo o arquivo no Visual Studio Code e inspecionando os erros do esquema.

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

Erros como uma configuração inválida de activePageName são exemplos de erros sem bloqueio que são corrigidos automaticamente. O aviso é necessário para lhe dar a chance de evitar salvar o relatório com o autofix, evitando assim qualquer potencial perda de trabalho.

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ê quiser 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 marcador manterá sua configuração.

Cenário: copiei uma pasta de página 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 oferecer suporte a detalhamento e 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.

Considerações e limitações do PBIR

PBIR está atualmente em versão prévia. Lembre-se:

• Limitações de serviço
  • As exibições móveis não são exibidas nos aplicativos do Power BI.
  • Não pode ser implantado com pipelines de implantação.
  • Não pode ser salvo como uma cópia.
• Relatórios grandes com mais de 500 arquivos apresentam problemas de desempenho de criação (a visualização do relatório não é afetada), incluindo:
  • Salvando no Power BI Desktop
  • Sincronização na integração Fabric Git
• Depois que um relatório é convertido de PBIR-Legacy para PBIR, não é possível revertê-lo.
• A conversão de um arquivo PBIP em um arquivo PBIX usando o recurso "Salvar como" incorpora o relatório PBIR no arquivo PBIX, transportando todas as limitações do PBIR para o PBIX.

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

• Máximo de 1.000 páginas por relatório.
• Máximo de 300 recursos visuais por página.
• Máximo de 5 MB para cada arquivo de favoritos.
• 1 MB no máximo para cada arquivo.
• 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 20 MB para todos os arquivos de relatório.

Durante a visualização pública, Fabric Git Integration e Fabric REST APIs continuam a usar PBIR-Legacy (report.json) ao exportar as definições de relatório. No entanto, se o relatório for importado para o Fabric usando o formato PBIR, ambos os recursos começarão a exportar a definição do relatório usando o formato PBIR.

Conteúdo relacionado

• Pasta do modelo semântico do projeto do Power BI Desktop
• Projetos do Power BI Desktop