Partilhar via

Pasta de relatório de projeto do Power BI Desktop

  • Artigo

Importante

Os projetos do Power BI Desktop estão atualmente em visualização.

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 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:

Property Descrição
connectionString A cadeia de conexão referente ao modelo semântico remoto.
pbiModelDatabaseName A ID do modelo semântico remoto.
Tipo de conexão Tipo de ligação. Para o 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": "EntityDataSource"
    }
  }
}

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. Se quiser forçar a abertura do relatório no live connect (por exemplo, para trabalhar com medidas a nível de relatório), podes ter múltiplos ficheiros definition*.pbir, como um com uma ligação byPath e outro com uma ligação byConnection. No entanto, apenas o arquivo definition.pbir não é ignorado ao importar a definição por meio do Fabric Git.

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

Esse 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 (arquivo report.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 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

Importante

Por favor, considere todas as limitações do PBIR durante a fase de visualização.

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.

Screenshot de diffs PBIR amigáveis.

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

Captura de tela da pasta de definição dentro de uma pasta pbip 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.

    Captura de tela do prompt para atualizar para PBIR.

    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
Ficheiro/Pasta Necessário Descrição
Favoritos\ Não Pasta que contém todos os arquivos de favoritos do relatório.
── [bookmarkName].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 visual.
──────── mobile.json Não Metadados visuais de layout móvel, como posição e formatação móveis.
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' será mantido 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 tela da propriedade do nome do PBIR.

Renomear a propriedade 'name' dentro de cada arquivo JSON é suportado, 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í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.

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 tela da dica de ferramenta prompt PBIR JSON Schema.

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

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 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. Usar um nome ou tipo de propriedade errado pode ser facilmente detetado diretamente no Visual Studio Code:

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

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:

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

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.

Captura de tela do erro de desbloqueio do PBIR de prompt.

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 favoritos 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 para a 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/bugs do serviço
    • As vistas móveis não são apresentadas nas Aplicações do Power BI.
    • As páginas ocultas são expostas na navegação dos Aplicativos do Power BI.
    • Não é possível implantar com pipelines de implantação.
    • Não pode ser salvo como uma cópia.
  • 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