Leggi in inglese

Condividi tramite

Cartella di report del progetto di Power BI Desktop

  • Articolo

Importante

Progetti di Power BI Desktop è 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 di report

.pbi\localSettings.json

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:

  • Oggetti visivi dell'archivio dell'organizzazione: le organizzazioni possono approvare e distribuire oggetti visivi personalizzati in Power BI per l'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 di modifiche al batch modificando il file di risorse in 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.

definition.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 stato aperto da un file pbip. L'apertura di un pbir apre anche il modello semantico se è presente un riferimento relativo usando byPath.

Esempio definition.pbir:

JSON 
{
  "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
connectionString Stringa di connessione che fa riferimento al modello semantico remoto.
pbiModelDatabaseName ID modello semantico remoto.
connectionType 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.

Esempio con byConnection:

JSON 
{
  "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 distribuisci un report tramite l'API REST dell'infrastruttura , è necessario usare riferimenti byConnection.

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.

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

Questo file specifica anche i formati di definizione 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 (\cartella definition).

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

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 Mail Luck!.

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 intuitive.

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 del batch in tutti gli oggetti visivi usando uno script (ad esempio, nascondere i filtri a livello di oggetto visivo)

Abilitare la funzionalità Anteprima formato PBIR

Il salvataggio come progetto di Power BI con PBIRL è 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 PBIP 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 upgrade a PBIR.

    Importante

    Dopo l'aggiornamento a PBIR, non è possibile tornare a PBIR-Legacy. Se si ritiene di voler ripristinare PBIR-Legacy, salvare prima una copia dei file PBIP.

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à nuovamente di eseguire l'upgrade.

Pubblicare un report PBIR nel servizio

Durante la fase di anteprima, l'unico modo per pubblicare un report con il formato PBIR è tramite Fabric Git Integration. Ciò comporta la connessione dell'area di lavoro a un repository Git e il push del report PBIR a esso, che può quindi essere sincronizzato con l'area di lavoro del servizio in una fase successiva.

Se si vuole convertire un report esistente in PBIR nel servizio, seguire questa procedura:

  1. Connettere l'area di lavoro a Git.
  2. Clonare il repository Git nel file system locale.
  3. Aprire il report in Power BI Desktop aprendo il file definition.pbir.
  4. Salvare il report e scegliere di eseguire l'upgrade a PBIR.
  5. Eseguire il commit e la sincronizzazione delle modifiche in Git.
  6. Eseguire l’upgrade dell'area di lavoro con le modifiche più recenti da Git.

File e cartelle PBIR

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

Markdown 
├── 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 oggetti visivi della pagina.
────── [visualName]\ No Una cartella per oggetto visivo.
──────── mobile.json No Metadati del layout per dispositivi mobili di visualizzazione, come ad esempio posizione e formattazione per dispositivi mobili.
Per ulteriori informazioni, vedere schema.
──────── visual.json Sì Metadati visivi, come ad esempio posizione e formattazione, 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à salvato in modo permanente 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.

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 della descrizione comando PBIR 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 ignorerà queste annotazioni, possono essere utili per applicazioni esterne come gli 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.

JSON 
{
  "$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 della conferma del comando PBIR Schema JSON.

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 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 PBIR del comando.

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 mancato blocco PBIR del comando.

Gli errori, come ad esempio una configurazione activePageName, sono esempi di errori non bloccanti risolti automaticamente. L'avviso è necessario per evitare di salvare il report con il prefisso automatico, 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 riferimenti di rilievo. 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 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.

Vedere Considerazioni e limitazioni

PBIR è attualmente in anteprima. Tenere presente quanto segue:

  • Limitazioni/bug del servizio
    • Non è possibile distribuirlo con le pipeline di distribuzione.
    • Non è possibile salvare come copia.
    • Non è possibile utilizzare le API dei report di Power BI: Clone Report, Update Report Content
  • Report di grandi dimensioni con più di 500 file riscontrano problemi di prestazioni di creazione (la visualizzazione dei report non è interessata), tra cui:
    • 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.
  • 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 oggetti visivi massimi per pagina.
  • 5 mb max per ogni file di segnalibro.
  • 1 mb max per ogni file.
  • 1.000 file max di pacchetti di risorse per report.
  • Dimensioni massime di 300 mb per tutti i file del pacchetto di risorse.
  • Dimensioni massime di 20 mb per tutti i file di report.

Durante l'anteprima, le API Fabric Git Integration e Fabric REST continuano a usare PBIR-legacy (report.json) durante l'esportazione delle definizioni dei report. Tuttavia, se il report viene importato in Fabric usando il formato PBIR, entrambe le funzionalità iniziano a esportare la definizione del report usando il formato PBIR.

Contenuto correlato