Cartella di report del progetto di Power BI Desktop

Questo articolo descrive i file e le sottocartelle nella cartella Report di un progetto di Microsoft Power BI Desktop. I file e le sottocartelle rappresentano qui un report di Power BI. A seconda del progetto, la cartella del report può includere:

1 - Questo file è obbligatorio.
2 - Questo file è necessario per PBIR-Legacy formato.
3 - Questo file è necessario per il formato PBIR.

Non tutte le cartelle del report del progetto includono tutti i file e le sottocartelle descritte qui.

File del rapporto

.pbi\localSettings.jsattivato

Contiene le impostazioni del report valide solo per l'utente corrente e il computer locale. Deve essere incluso in gitIgnore o in altre esclusioni del controllo del codice sorgente. Per impostazione predefinita, Git ignora questo file.

Per ulteriori informazioni, vedere il documento dello schema localSettings.json.

CustomVisuals\

Sottocartella contenente i metadati per gli oggetti visivi personalizzati nel report. Power BI supporta tre tipi di oggetti visivi personalizzati:

  • Immagini visuali dell'organizzazione: le organizzazioni possono approvare e distribuire immagini visuali personalizzate in Power BI per la loro organizzazione. Per ulteriori informazioni, vedere Archivio dell'organizzazione.
  • Oggetti visivi di Power BI di AppSource: denominati anche "Oggetti visivi personalizzati pubblici". Questi oggetti visivi sono disponibili in Microsoft AppSource. Gli sviluppatori di report possono installare questi oggetti visivi direttamente da Power BI Desktop.
  • File visivi personalizzati: denominati anche "Oggetti visivi personalizzati privati". I file possono essere caricati nel report caricando un pacchetto pbiviz.

Solo gli oggetti visivi personalizzati privati vengono caricati nella cartella CustomVisuals. Gli oggetti visivi AppSource e Organization vengono caricati automaticamente da Power BI Desktop.

RegisteredResources\

Sottocartella che include file di risorse specifici del report e caricati dall'utente, come ad esempio temi personalizzati, immagini e oggetti visivi personalizzati (file pbiviz).

Gli sviluppatori sono responsabili dei file qui presenti e le modifiche sono supportate. Ad esempio, è possibile modificare un file e dopo un riavvio di Power BI Desktop, il nuovo file viene caricato nel report. Questa cartella può sbloccare alcuni scenari utili, come ad esempio:

  • Creazione di temi personalizzati all'esterno di Power BI Desktop usando lo schema pubblico.
  • Applicazione delle modifiche in batch modificando il file di risorse su più report. Ad esempio, è possibile modificare il tema personalizzato aziendale, invertire i temi chiari e quelli scuri e modificare le immagini del logo.

Ogni file di risorse deve avere una voce corrispondente nel file report.json. Le modifiche ai file RegisteredResources sono supportate solo per le risorse già caricate che causano la registrazione della risorsa in report.json da parte di Power BI Desktop.

semanticModelDiagramLayout.json

Contiene diagrammi del modello di dati che descrivono la struttura del modello semantico associato al report. Questo file non supporta le modifiche esterne.

definizione.pbir

Contiene la definizione complessiva di un report e delle impostazioni principali. Questo file contiene anche il riferimento al modello semantico usato dal report. Power BI Desktop può aprire direttamente un file PBIR, esattamente come se il report fosse aperto da un file PBIP. L'apertura di un file PBIR apre anche il modello semantico insieme a se è presente un riferimento relativo usando byPath.

Esempio definizione.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"
    }    
  }
}

La definizione include la proprietà datasetReference, che fa riferimento al modello semantico usato nel report. Il riferimento può essere:

byPath : specifica un percorso relativo verso la cartella del modello semantico di destinazione. I percorsi assoluti non sono supportati. Una barra (/) viene utilizzata come separatore di cartelle. Se usato, Power BI Desktop apre anche il modello semantico in modalità di modifica completa.

byConnection : specifica la connessione a un modello semantico in un'area di lavoro Fabric usando una stringa di connessione. Quando si usa un riferimento byConnection, Power BI Desktop non apre il modello semantico in modalità di modifica.

Usando un riferimento byConnection, è necessario specificare le proprietà seguenti:

Proprietà Descrizione
Stringa di connessione Stringa di connessione che fa riferimento al modello semantico in un'area di lavoro Fabric.

Esempio con 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]"
    }
  }
}

Quando si distribuisce un report tramite l'API REST di Infrastruttura, è sufficiente specificare la semanticmodelid proprietà . Per esempio:

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

Quando si distribuisce un report tramite Fabric REST API, è necessario usare byConnection riferimenti. Questa operazione non deve essere confusa con la modalità di archiviazione di un modello semantico, ad esempio DirectQuery. Nel datasetReference report specifica solo il modello semantico a cui si connette il report, non definisce il modo in cui il modello archivia o accede ai dati.

Più file *.pbir

Quando il modello semantico e il report condividono la stessa area di lavoro, Fabric Git Integration esporta sempre le definizioni con un byPath riferimento al modello semantico. Se si desidera forzare l'apertura del report in connessione in tempo reale (ad esempio, per usare misure a livello del report), si possono avere più file *.pbir, ad esempio uno con una connessione byPath e un altro con una connessione byConnection. Fabric Git Integration elabora solo il file definition.pbir e ignora tutti gli altri file *.pbir. Tuttavia, questi file possono coesistere nello stesso repository.

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

Il definition.pbir file specifica anche i formati di definizione del report supportati tramite la proprietà 'version'.

Versione Formati supportati
1.0 La definizione del report deve essere archiviata come PBIR-Legacy nel file report.json.
4.0 o versione successiva La definizione del report può essere archiviata come PBIR-Legacy (file report.json) o PBIR (\nella cartella definition).

Per ulteriori informazioni, vedere il documento dello schema definition.pbir.

mobileState.json

Contiene le impostazioni relative all'aspetto e al comportamento del report durante il rendering in un dispositivo mobile. Questo file non supporta le modifiche esterne.

report.json

Questo file contiene la definizione del report nel formato legacy del report di Power BI (PBIR-Legacy) e non supporta le modifiche esterne.

definizione\ cartella

Questa cartella è disponibile solo se il progetto di Power BI viene salvato usando il formato di report avanzato (PBIR) di Power BI. Sostituisce il file report.json.

Piattaforma

File della piattaforma fabric che contiene le proprietà essenziali per stabilire e mantenere la connessione tra gli elementi di Fabric e di Git.

Per ulteriori informazioni, vedere Integrazione di Git per i file di sistema generati automaticamente.

Formato PBIR

Il salvataggio dei file di progetto di Power BI (PBIP) tramite il formato PBIR (Power BI Enhanced Report Format) di Power BI migliora notevolmente il rilevamento delle modifiche e la risoluzione dei conflitti di unione usando file JSON formattati correttamente.

Screenshot delle differenze PBIR amichevoli.

Ogni pagina, oggetto visivo, segnalibro e così via, è organizzata in un singolo file separato all'interno di una struttura di cartelle. Questo formato è ideale per la risoluzione dei conflitti di co-sviluppo.

Screenshot della cartella PBIR intuitiva.

A differenza di PBIR-Legacy (report.json), PBIR è un formato documentato pubblicamente che supporta le modifiche provenienti da applicazioni diverse da Power BI. Ogni file ha uno schema JSON pubblico che, oltre a documentare il file, consente agli editor di codice come Visual Studio Code di eseguire la convalida della sintassi durante l'editing.

Alcuni degli scenari possibili ora disponibili con PBIR includono:

  • Copiare pagine, oggetti visivi, segnalibri tra i report.
  • Garantire la coerenza di un set di oggetti visivi in tutte le pagine, copiando e incollando i file visivi.
  • Facile da trovare e sostituire tra più file di report.
  • Applicare una modifica collettiva in tutti gli elementi visivi usando uno script (ad esempio, nascondere i filtri a livello di elemento visivo)

Salvare come progetto usando PBIR

Quando si salva un progetto usando PBIR, il report viene salvato all'interno di una cartella denominata \definition all'interno della cartella del report:

Screenshot della cartella di definizione all'interno di una cartella PBIP del report.

Ulteriori informazioni sulla struttura delle cartelle PBIR.

Cartelle e file PBIR

La definizione del report viene archiviata all'interno della cartella definition\ con la struttura seguente:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json
File/Cartella Obbligatorio Descrizione
segnalibri\ NO Cartella contenente tutti i file di segnalibro del report.
'} [bookmarkName].bookmark.json NO Metadati dei segnalibri, come ad esempio oggetti visivi di destinazione e filtri.
Per ulteriori informazioni, vedere schema.
'* bookmarks.json NO Metadati dei segnalibri, come ad esempio l'ordine dei segnalibri e i gruppi.
Per ulteriori informazioni, vedere schema.
pagine\ Sì Cartella contenente tutte le pagine del report.
[pageName]\ Sì Una cartella per pagina.
──── oggetti visivi\ NO Cartella contenente tutti gli elementi visivi della pagina.
────── [visualName]\ NO Una cartella per oggetto visivo.
─────── mobile.json NO Metadati del layout visivo per dispositivi mobili, come la posizione e la formattazione.
Per ulteriori informazioni, vedere schema.
──────── visual.json Sì Metadati visivi, come la posizione e la formattazione, possono essere oggetto di query.
Per ulteriori informazioni, vedere schema.
──── page.json Sì Metadati della pagina, come ad esempio filtri a livello di pagina e formattazione.
Per ulteriori informazioni, vedere schema.
* pages.json NO Metadati delle pagine, come ad esempio l'ordine della pagina e la pagina attiva.
Per ulteriori informazioni, vedere schema.
version.json Sì La versione del file PBIR, tra gli altri fattori, determina i file necessari da caricare.
Per ulteriori informazioni, vedere schema
reportExtensions.json NO Estensioni del report, come ad esempio misure a livello di report.
Per ulteriori informazioni, vedere schema
report.json Sì Metadati del report, come ad esempio filtri a livello di report e formattazione.
Per ulteriori informazioni, vedere schema

Importante

Alcuni file di metadati del report, ad esempio visual.json o bookmarks.json, possono essere salvati con valori di dati dal modello semantico. Ad esempio, se si applica un filtro a un oggetto visivo per il campo 'Company' = 'Contoso', il valore 'Contoso' verrà mantenuto come parte dei metadati. Questo vale anche per altre configurazioni, come le selezioni del filtro, la larghezza delle colonne personalizzate della matrice e la formattazione per serie specifiche.

Convenzione di denominazione PBIR

Tutti i nomi all'interno delle parentesi quadre ([]) nella tabella precedente seguono una convenzione di denominazione predefinita, ma possono essere rinominati con nomi più indicativi. Per impostazione predefinita, le pagine, gli oggetti visivi e i segnalibri usano il nome dell'oggetto del report come nome di file o cartella. Questi nomi di oggetto sono inizialmente un identificatore univoco di 20 caratteri, come ad esempio '90c2e07d8e84e7d5c026'.

Screenshot della proprietà PBIR name.

La ridenominazione della proprietà 'name' all'interno di ogni file JSON è supportata, ma potrebbe interrompere i riferimenti esterni sia all'interno che all'esterno del report. Il nome dell'oggetto e/o il nome del file/cartella devono essere costituiti da uno o più caratteri di scrittura (lettere, cifre, caratteri di sottolineatura) o trattini.

Dopo aver rinominato i file o le cartelle PBIR, è necessario riavviare Power BI Desktop. Al riavvio, Power BI Desktop manterrà i nomi di file o cartelle originali durante il salvataggio.

Copiare il nome dell'oggetto report

Ogni oggetto del report viene salvato in una cartella o in un file separato, ma il nome della cartella non è sempre ovvio. Per semplificare questa operazione, è possibile copiare il nome di qualsiasi nome dell'oggetto report (incluse pagine, oggetti visivi, segnalibri e filtri) direttamente da Power BI negli Appunti.

Schermata di un report con una freccia che punta da uno degli elementi visivi al nome del file corrispondente.

  1. Passa a File > Opzioni e impostazioni > Impostazioni report > Oggetti report e abilita l'impostazione Copia i nomi degli oggetti al clic destro sui oggetti del report. È necessario eseguire questa operazione una sola volta.

    Screenshot delle impostazioni del rapporto sugli oggetti del report.

  2. Fare clic con il pulsante destro del mouse su qualsiasi oggetto report e selezionare Copia nome oggetto.

    Screenshot di un report desktop con il nome dell'oggetto copia selezionato.

Con il nome dell'oggetto copiato negli Appunti, è possibile inserirlo facilmente nella barra di ricerca di Esplora risorse o Visual Studio Code per individuare o identificare il nome dell'oggetto all'interno della cartella PBIR.

Screenshot della barra di ricerca con il nome dell'oggetto.

Schemi JSON PBIR

Ogni file Json PBIR include una dichiarazione di schema Json nella parte superiore del documento. Questo URL dello schema è accessibile pubblicamente e può essere usato per altre informazioni sulle proprietà e gli oggetti disponibili per ogni file. Fornisce inoltre IntelliSense e la convalida predefinite durante la modifica con editor di codice come Visual Studio Code.

Screenshot dell'effetto di sovrapposizione PBIR dello Schema JSON.

L'URL dello schema definisce anche la versione del documento, che dovrebbe cambiare man mano che la definizione del report si evolve.

Tutti gli schemi JSON vengono pubblicati qui.

Annotazioni PBIR

È possibile includere annotazioni come coppie nome-valore all'interno della definizione del report per ogni visual, page e report. Anche se Power BI Desktop ignora queste annotazioni, può essere utile per applicazioni esterne come script.

Ad esempio, è possibile specificare il valore defaultPage per il report nel file report.json, che può quindi essere utilizzato da uno script di distribuzione.

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

Modifiche esterne ai file PBIR

È possibile modificare i file JSON PBIR supportati in un editor di codice come Visual Studio Code o un altro strumento esterno mentre il progetto rimane aperto in Power BI Desktop. Quando si salvano i file, Power BI Desktop rileva le modifiche e visualizza il banner Applica modifiche esterne. Selezionare Applica modifiche esterne per ricaricare la definizione del report senza chiudere e riaprire il progetto.

Prima di modificare i file PBIR esternamente, salvare eventuali modifiche in Power BI Desktop. Se Power BI Desktop ha modifiche non salvate quando si applicano le modifiche esterne, segnala che le modifiche non salvate verranno sovrascritte. Per il flusso di lavoro completo e le limitazioni, vedere Modificare i file PBIP all'esterno di Power BI Desktop.

I file PBIR devono essere conformi ai relativi schemi JSON. VS Code identifica i problemi, ad esempio un nome di proprietà non supportato o un tipo di proprietà non corretto:

Screenshot del prompt di convalida dello schema JSON PBIR.

Le modifiche esterne al contenuto PBIR possono causare errori quando si applicano le modifiche o si aprono i file in Power BI Desktop. Questi errori possono essere di due tipi:

Gli errori di blocco impediscono Power BI Desktop di caricare le modifiche del report. Questi errori identificano il problema e il file che è necessario correggere prima di applicare di nuovo le modifiche:

Screenshot dell'errore di blocco del prompt PBIR.

Gli errori, ad esempio uno schema non valido o le proprietà necessarie mancanti, bloccano gli errori. Per identificare questi errori, aprire il file in VS Code ed esaminare i messaggi di convalida dello schema.

Gli errori non bloccanti non impediscono a Power BI Desktop di aprire il report e vengono risolti automaticamente.

Screenshot dell'errore di non-blocco PBIR del prompt.

Una configurazione non valida activePageName è un esempio di errore non bloccante che Power BI Desktop corregge automaticamente. L'avviso consente di esaminare la correzione prima di salvare il report e sovrascrivere la definizione esterna.

Errori PBIR comuni

Scenario:dopo aver rinominato le cartelle degli oggetti visivi o delle pagine, l'oggetto visivo o la pagina non compare più all'apertura del report.

Soluzione: verificare se il nome è conforme alla convenzione di denominazione. In caso contrario, Power BI Desktop ignora il file o la cartella e la considera come file utente privato.

Scenario:i nuovi oggetti report vengono denominati in modo diverso da altri. Ad esempio, la maggior parte delle cartelle di pagina è denominata "ReportSection0e71dafbc949c0853608", mentre alcune sono denominate "1b3c2ab12b603618070b".

Soluzione: PBIR ha adottato una nuova convenzione di denominazione per ogni oggetto, ma si applica solo ai nuovi oggetti. Quando si salva un report esistente come PBIP, i nomi correnti devono essere mantenuti per evitare di rompere i riferimenti. Se si vuole coerenza, è consentito uno script per rinominare un batch.

Scenario:ho copiato un file di segnalibro e al salvataggio la maggior parte della configurazione del segnalibro è stata eliminata.

Soluzione: questo comportamento è intenzionale, i segnalibri del report acquisiscono lo stato di una pagina del report insieme a tutti i relativi oggetti visivi. Poiché lo stato acquisito ha origine da un'altra pagina del report con oggetti visivi diversi, eventuali oggetti visivi non validi vengono rimossi dalla configurazione del segnalibro. Se si copiano anche gli oggetti visivi e la pagina dipendenti, il segnalibro mantiene la sua configurazione.

Scenario:ho copiato una cartella di pagina da un altro report e si è verificato un errore che indica che i "Valori per la proprietà 'pageBinding.name' devono essere univoci."

Soluzione: l'oggetto pageBinding è necessario per supportare le descrizioni comando drill-through e di pagina. Poiché potrebbero essere referenziati da altre pagine, il nome deve essere univoco all'interno del report. Nella pagina appena copiata, assegnare un valore univoco per risolvere l'errore. Da giugno 2024, questa situazione non è più un problema perché il nome pageBinding è un GUID per impostazione predefinita.

Convertire il report esistente in PBIR

PBIR è disponibile a livello generale ed è il formato predefinito del report. È comunque possibile aprire report che usano PBIR-Legacy in Power BI Desktop e nel servizio Power BI. Quando si modifica e si salva un report PBIR-Legacy, Power BI lo converte automaticamente e in modo invisibile in PBIR.

Prima della conversione, Power BI crea un backup del report:

  • Power BI Desktop mantiene il backup per 30 giorni in una delle posizioni seguenti:
    • Versione di Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Versione del programma di installazione eseguibile: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • Il servizio Power BI mantiene il backup PBIR-Legacy per 28 giorni. Per ripristinarlo, aprire Impostazioni report dall'area di lavoro e selezionare Ripristina come PBIR-Legacy. Questo backup viene creato solo per i report convertiti direttamente nel servizio Power BI.

Il ripristino di un backup PBIR-Legacy non impedisce un'altra conversione. Per mantenere un report in formato PBIR-Legacy, non modificarlo nel servizio Power BI o usare una versione di Power BI Desktop rilasciata prima di settembre 2026.

Considerazioni e limitazioni di PBIR

Tenere presenti le considerazioni e le limitazioni seguenti:

  • I filtri automatici visivi vengono mantenuti nel file PBIR visual.json solo dopo l'espansione del riquadro filtro almeno una volta durante la modifica del report.
  • Se Power BI non converte un report PBIR-Legacy in PBIR quando si modifica e lo si salva, la conversione ha riscontrato un problema di prodotto. Creare una richiesta di supporto per segnalare il problema.

Limitazioni delle dimensioni PBIR applicate dal servizio:

  • 1.000 pagine massime per report.
  • 1000 elementi visivi al massimo per pagina.
  • 1.000 file max di pacchetti di risorse per report.
  • Dimensioni massime di 300 mb per tutti i file del pacchetto di risorse.
  • Dimensione massima complessiva di 300 MB per tutti i file di report.

Importante

Se si raggiungono i limiti sopra indicati, è consigliabile ottimizzare il report. Vedere il documento Ottimizzazione di Power BI.

Integrazione Git di Fabric e API REST di Fabric esportano le definizioni dei report utilizzando PBIR.

Contenuto correlato

  • Ultimo aggiornamento: