Condividi tramite

Cartella di report del progetto di Power BI Desktop

Importante

I progetti di Power BI Desktop sono attualmente in anteprima.

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 quando si salva in formato PBIR-Legacy.
3 - Questo file è necessario quando si salva in 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, che durante l'anteprima non supporta la modifica. 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. Durante l'anteprima, questo file non supporta la modifica esterna.

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:

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

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 un modello semantico remoto nel servizio Power BI 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 remoto.
pbiModelDatabaseName ID modello semantico remoto.
tipo di connessione Tipo di connessione. Per il modello semantico remoto del servizio, questo valore deve essere pbiServiceXmlaStyleLive.
pbiModelVirtualServerName Proprietà interna che deve avere il valore sobe_wowvirtualserver.
pbiServiceModelId Proprietà interna che deve avere il valore null.
nome Proprietà interna che deve avere il valore EntityDataSource.

Esempio con 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": "[Semantic Model Id]",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": "EntityDataSource"
    }
  }
}

Importante

Quando si distribuisce un report tramite Fabric REST API, è necessario usare byConnection riferimenti.

Quando il modello semantico e il report condividono la stessa area di lavoro, Fabric Git Integration usa sempre un byPath riferimento al modello semantico. Se vuoi forzare l'apertura del report in Live Connect (ad esempio, per lavorare con misure a livello di report), è possibile disporre di più file definition*.pbir, come uno con una connessione tramite byPath e un altro con una connessione tramite 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

Questo file specifica anche i formati dei rapporti 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

Importante

Prendere in considerazione tutte le limitazioni PBIR durante la fase di anteprima.

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)

Abilitare la funzionalità Anteprima formato PBIR

Il salvataggio come progetto di Power BI con PBIR è attualmente in anteprima. Prima di usarlo, abilitarlo nelle funzionalità di anteprima di Power BI Desktop:

Passare a File > Opzioni e impostazioni > Opzioni > Funzionalità di anteprima e selezionare la casella accanto a Archiviare i report usando il formato di metadati avanzato (PBIR).

Salvare come progetto usando PBIR

Con la funzionalità Anteprima PBIR abilitata, quando si salva un progetto, il report viene salvato all'interno di una cartella denominata \definizione 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.

Convertire il report esistente in PBIR

Se si dispone già di un PBIP usando il formato PBIR-Legacy, è possibile convertirlo in PBIR come indicato di seguito:

  1. Aprire il PBIP in Power BI Desktop.

  2. Verificare che la funzionalità di anteprima sia abilitata.

  3. Salvare il progetto. Compare un prompt che chiede di eseguire l'upgrade a PBIR.

  4. Selezionare Aggiorna.

    Screenshot della richiesta di aggiornamento a PBIR.

    Importante

    Dopo l'aggiornamento a PBIR, non è possibile ripristinare PBIR-Legacy dall'interfaccia utente. Per ripristinare PBIR-Legacy, salvare una copia dei file PBIP.

    Power BI Desktop crea automaticamente un backup del report prima dell'aggiornamento a PBIR. Questo backup viene conservato 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 file PBIR-Legacy esistente (report.json) viene sostituito con una cartella\definizione contenente la rappresentazione PBIR del report.

Se si seleziona Mantieni il formato corrente, desktop non chiederà di nuovo di eseguire l'aggiornamento.

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 usando un editor di codice come Visual Studio Code o uno strumento esterno, purché il file rispetti lo schema JSON. L'uso di un nome o di un tipo di proprietà errato può essere facilmente rilevato direttamente in Visual Studio Code:

Screenshot del prompt di convalida dello schema JSON PBIR.

Le modifiche esterne al contenuto PBIR potrebbero causare errori durante la riapertura dei file in Power BI Desktop. Questi errori possono essere di due tipi:

Gli errori di blocco impediscono a Power BI Desktop di aprire il report. Questi errori consentono di identificare il problema e il file che causa l'errore che deve essere risolto prima della riapertura:

Screenshot dell'errore di blocco del prompt PBIR.

Gli errori, come ad esempio uno schema non valido o le proprietà necessarie mancanti sono considerati errori di blocco. Questi errori possono essere facilmente identificati aprendo il file in Visual Studio Code ed esaminando gli errori 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.

Gli errori, come ad esempio una configurazione non valida del activePageName, sono esempi di errori non bloccanti risolti automaticamente. L'avviso è necessario per darti la possibilità di evitare di salvare il report con la correzione automatica, impedendo così qualsiasi potenziale perdita di lavoro.

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.

Considerazioni e limitazioni di PBIR

PBIR è attualmente in anteprima. Tenere presenti le limitazioni seguenti:

  • Limitazioni/bug del servizio
  • Report di grandi dimensioni con più di 500 file riscontrano problemi di prestazioni di creazione (la visualizzazione dei report non è interessata), tra cui:
    • Il salvataggio in Power BI Desktop
    • Sincronizzazione nell'integrazione Git di Fabric
  • Una volta convertito un report da PBIR-Legacy a PBIR, non è possibile eseguirne il rollback. Anche se al momento della conversione viene creato un backup.
  • La conversione di un file PBIP in un file PBIX tramite la funzionalità "Salva con nome" incorpora il report PBIR all'interno del file PBIX, portando tutte le limitazioni PBIR nel PBIX.

Limitazioni delle dimensioni PBIR applicate dal servizio:

  • 1.000 pagine massime per report.
  • 300 elementi visivi massimi 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.

Le Fabric Git Integration e le Fabric REST APIs esportano i report usando il formato attualmente applicato nel servizio. Se un report viene creato o importato in Fabric usando il formato PBIR, verrà esportato in PBIR. Analogamente, se un report è PBIR-Legacy, verrà esportato nel formato PBIR-Legacy.

Contenuto correlato