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:

• .pbi\
  • localSettings.json
• PersonalVisuals\
• StaticResources\
  • RecursosRegistrados\
• semanticModelDiagramLayout.json
• definição.pbir¹
• mobileState.json
• ^{report.json 2}
• definição\^{pasta 3}
• .plataforma

1 - Este ficheiro é obrigatório.
2 - Este arquivo é necessário ao salvar no formato PBIR-Legacy.
3 - Este arquivo é necessário ao salvar no 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.json

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.

PersonalVisuals\

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 do repositório organizacional - As organizações podem aprovar e implantar visuais personalizados no Power BI para 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.

RecursosRegistrados\

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 arquivo de recurso deve ter uma entrada correspondente no arquivo report.json, que durante a visualização não suporta edição. 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. Durante a pré-visualização, 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 pbir também abre o modelo semântico ao lado se houver uma referência relativa usando byPath.

Exemplo de definição.pbir:

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

A definição inclui a datasetReference propriedade, que faz referência ao modelo semântico usado 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 pasta. Quando usado, o Power BI Desktop também abre o modelo semântico no modo de edição completa.

byConnection - Especifica um modelo semântico remoto no serviço do Power BI 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:

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, o 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 por meio da propriedade 'version'.

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 de malha que contém propriedades vitais para estabelecer e manter a conexão entre itens de malha 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.

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.

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

Ativar o recurso de visualização do formato PBIR

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

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

Salvar como um projeto usando PBIR

Com o recurso de visualização PBIR habilitado, quando você salva um projeto, seu relatório é salvo em uma pasta chamada \definition dentro da pasta de relatório:

Saiba mais sobre a estrutura de pastas PBIR.

Converter PBIP existente em PBIR

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

1. Abra o PBIP no Power BI Desktop.

2. Certifique-se de que a funcionalidade de pré-visualização está ativada.

3. Salve o projeto. Um prompt é exibido 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 pode querer reverter para PBIR-Legacy, salve uma cópia de seus arquivos PBIP primeiro.

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

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

Publicar um relatório PBIR para serviço

Enquanto estiver na fase de visualização , a única maneira de publicar um relatório com o formato PBIR é por meio da 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 ser sincronizado com o espaço de trabalho de serviço em um estágio posterior.

Se desejar converter um relatório existente em PBIR no serviço, siga estas 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 definition.pbir arquivo.
4. Salve o relatório e opte por atualizar para PBIR.
5. Confirme e sincronize as alterações no Git.
6. Atualize o espaço de trabalho com as alterações mais recentes do Git.

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

Convenção de nomenclatura PBIR

Por padrão, as páginas, elementos visuais e marcadores usam o nome do objeto de relatório como nome de arquivo ou pasta. Os nomes dos objetos são, por padrão, um identificador exclusivo de 20 caracteres, como '90c2e07d8e84e7d5c026'.

Há suporte para renomear o arquivo ou pasta e o Power BI preserva o nome do arquivo original ao salvar. No entanto, renomear a propriedade 'name' dentro de cada arquivo JSON, embora também seja suportado, pode resultar na quebra de referências externas (dentro e fora do relatório). O nome do objeto e/ou o nome do arquivo/pasta devem consistir em um ou mais caracteres de palavra (letras, dígitos, sublinhados) ou hífenes.

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.

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.

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. Usar um nome ou tipo de propriedade errado pode ser facilmente detetado 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 ofensivo que deve ser corrigido antes de reabrir:

Erros como um esquema inválido ou propriedades necessá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 de esquema.

Os 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 activePageName inválida 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 a correção automática, evitando assim qualquer perda potencial de trabalho.

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. Quando você salva um relatório existente como PBIP, os nomes atuais devem ser preservados para evitar referências de quebra. 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. 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."

Solução: O objeto pageBinding é necessário para dar suporte a dicas de ferramentas de detalhamento e 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.

Considerações e limitações do PBIR

O PBIR está atualmente em pré-visualização. tenha em consideração o seguinte:

• Limitações do serviço
  • Não pode ser incluído nos Aplicativos do Power BI.
  • Não é possível fazer o download como PBIX.
  • Não pode ser exportado para PPTX ou PDF.
  • Não pode ser incluído em Subscrições.
  • Não é possível implantar com pipelines de implantação.
  • Os layouts móveis não são aplicados.
  • Não pode ser salvo como uma cópia.
  • Não pode ser publicado a partir do Power BI Desktop.
  • Não pode ser carregado para o espaço de trabalho como PBIX.
  • Não pode ser utilizado no Power BI Embedded.
• Relatórios grandes com mais de 500 arquivos enfrentam problemas de desempenho de criação (a visualização de relatórios não é afetada), incluindo:
  • Guardar no Power BI Desktop
  • Sincronização na integração do 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 dentro do arquivo PBIX, transportando todas as limitações do PBIR para o PBIX.

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

• 1.000 páginas máximas por relatório.
• 300 visuais máximos por página.
• 5 MB no máximo para cada ficheiro de favoritos.
• 1 MB no máximo para cada ficheiro.
• 1.000 arquivos de pacote de recursos máximos por relatório.
• Tamanho máximo de 300 MB para todos os arquivos do pacote de recursos.
• Tamanho máximo de 20 MB de todos os arquivos de relatório.

Durante a visualização pública, as APIs Fabric Git Integration e Fabric REST 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 de relatório usando o formato PBIR.

Conteúdos relacionados

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