Power BI Desktop-Projektberichtsordner

Wichtig

Power BI Desktop-Projekte befinden sich derzeit in der Vorschau.

In diesem Artikel werden die Dateien und Unterordner im Ordner Bericht eines Microsoft Power BI Desktop-Projekts beschrieben. Die hier aufgeführten Dateien und Unterordner stellen einen Power BI-Bericht dar. Abhängig von Ihrem Projekt kann der Berichtsordner Folgendes umfassen:

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• report.json²
• definition\ folder³
• .platform

1 – Diese Datei ist erforderlich.
2 – Diese Datei ist beim Speichern im PBIR-Legacy-Format erforderlich.
3 – Diese Datei ist beim Speichern im PBIR-Format erforderlich.

Nicht jeder Projektberichtsordner enthält alle hier beschriebenen Dateien und Unterordner.

Berichtsdateien

.pbi\localSettings.json

Enthält Berichtseinstellungen, die nur für den aktuellen Benutzer und den lokalen Computer gelten. Sie sollte in gitIgnore oder anderen Quellcodeverwaltungsausschlüssen enthalten sein. Standardmäßig ignoriert Git diese Datei.

Weitere Informationen finden Sie im Schemadokument zu localSettings.json.

CustomVisuals\

Ein Unterordner, der Metadaten für benutzerdefinierte Visuals im Bericht enthält. Power BI unterstützt drei Arten von benutzerdefinierten Visuals:

• Visuals im Organisationsspeicher: Organisationen können benutzerdefinierte Visuals für ihre Organisation genehmigen und in Power BI bereitstellen. Weitere Informationen finden Sie unter Organisationsspeicher.
• AppSource Power BI-Visuals: Auch bekannt als „Öffentliche benutzerdefinierte Visuals“. Diese Visuals sind über Microsoft AppSource verfügbar. Berichtsentwickler können diese Visuals direkt über Power BI Desktop installieren.
• Benutzerdefinierte visuelle Dateien: Auch bekannt als „Private benutzerdefinierte Visuals“. Die Dateien können durch Hochladen eines pbiviz-Pakets in den Bericht geladen werden.

Nur private benutzerdefinierte Visuals werden in den CustomVisuals-Ordner geladen. AppSource- und Organisationsvisuals werden automatisch von Power BI Desktop geladen.

RegisteredResources\

Ein Unterordner, der für den Bericht spezifische und vom Benutzer geladene Ressourcendateien enthält, z. B. benutzerdefinierte Designs, Bilder und benutzerdefinierte Visuals (pbiviz-Dateien).

Entwickler sind hier für die Dateien verantwortlich, und Änderungen werden unterstützt. Beispielsweise können Sie eine Datei ändern, und nach einem Neustart von Power BI Desktop wird die neue Datei in den Bericht geladen. Dieser Ordner kann die Blockierung einiger nützlicher Szenarien aufheben, z. B.:

• Erstellen benutzerdefinierter Themen außerhalb von Power BI Desktop mithilfe des öffentlichen Schemas.
• Anwenden von Batchänderungen durch Ändern der Ressourcendatei für mehrere Berichte. Beispielsweise können Sie das benutzerdefinierte Thema des Unternehmens wechseln, zwischen hellen und dunklen Themen wechseln und Logobilder ändern.

Jede Ressourcendatei muss einen entsprechenden Eintrag in der Datei report.json aufweisen, der während der Vorschau keine Bearbeitung unterstützt. Bearbeitungen an RegisteredResources-Dateien werden nur für bereits geladene Ressourcen unterstützt, die dazu führen, dass Power BI Desktop die Ressource in report.json registrieren.

semanticModelDiagramLayout.json

Enthält Datenmodelldiagramme, die die Struktur des dem Bericht zugeordneten Semantikmodells beschreiben. Während der Vorschau unterstützt diese Datei keine externe Bearbeitung.

definition.pbir

Enthält die Gesamtdefinition eines Berichts und die Kerneinstellungen. Diese Datei enthält auch den Verweis auf das vom Bericht verwendete Semantikmodell. Power BI Desktop kann eine pbir-Datei direkt öffnen, genau so, als würde der Bericht aus einer pbip-Datei geöffnet. Beim Öffnen einer pbir-Datei wird auch das Semantikmodell geöffnet, wenn ein relativer Verweis mit byPath verwendet wird.

Beispiel: definition.pbir:

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

Die Definition enthält die datasetReference-Eigenschaft, die auf das im Bericht verwendete Semantikmodell verweist. Der Verweis kann Folgendes sein:

byPath – Gibt einen relativen Pfad zum Ordner des Zielsemantikmodells an. Absolute Pfade werden nicht unterstützt. Ein Schrägstrich (/) wird als Ordnertrennzeichen verwendet. Bei Verwendung öffnet Power BI Desktop das Semantikmodell auch im vollständigen Bearbeitungsmodus.

byConnection – Gibt ein Remotesemantikmodell im Power BI-Dienst mithilfe einer Verbindungszeichenfolge an. Wenn ein byConnection-Verweis verwendet wird, öffnet Power BI Desktop das Semantikmodell nicht im Bearbeitungsmodus.

Bei Verwendung eines byConnection-Verweises müssen die folgenden Eigenschaften angegeben werden:

Eigenschaft	Beschreibung
connectionString	Die Verbindungszeichenfolge, die auf das Remotesemantikmodell verweist.
pbiModelDatabaseName	Die ID des Remotesemantikmodells.
connectionType	Der Typ der Verbindung. Für das Remotesemantikmodell des Diensts sollte dieser Wert pbiServiceXmlaStyleLive sein.
pbiModelVirtualServerName	Eine interne Eigenschaft, die den Wert sobe_wowvirtualserver haben sollte.

Beispiel für die Verwendung von 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
    }
  }
}

Wenn das semantische Modell und der Bericht denselben Arbeitsbereich gemeinsam nutzen, verwendet Fabric Git Integration immer einen byPath-Verweis auf das Semantikmodell.

In dieser Datei werden auch die unterstützten Berichtsdefinitionsformate über die Eigenschaft „version“ angegeben.

Version	Unterstützte Formate
1.0	Die Berichtsdefinition muss im PBIR-Legacy-Format in der Datei report.json gespeichert werden.
4.0 oder höher	Die Berichtsdefinition kann im PBIR-Legacy-Format (Datei report.json) oder im PBIR-Format (Ordner \definition) gespeichert werden.

Weitere Informationen finden Sie im definition.pbir-Schemadokument.

mobileState.json

Enthält Einstellungen für Berichtsdarstellung und -verhalten beim Rendern auf einem mobilen Gerät. Diese Datei unterstützt keine externe Bearbeitung.

report.json

Diese Datei enthält die Berichtsdefinition im Legacyformat für Power BI-Berichte (PBIR-Legacy) und unterstützt keine externe Bearbeitung.

definition\ folder

Dieser Ordner ist nur verfügbar, wenn das Power BI-Projekt im erweiterten Power BI-Berichtsformat (PBIR) gespeichert wird. Er ersetzt die Datei report.json.

Warnungsplattform beizubehalten.

Fabric-Plattformdatei, die Eigenschaften enthält, die für das Herstellen und Verwalten der Verbindung zwischen Fabric-Elementen und Git unerlässlich sind.

Weitere Informationen finden Sie unter Git-Integration automatisch generierte Systemdateien.

PBIR-Format

Wichtig

Beachten Sie alle Einschränkungen für das PBIR-Format während der Vorschauphase.

Durch das Speichern Ihrer Power BI-Projektdateien (PBIP) mit dem erweiterten Power BI-Berichtsformat (PBIR) werden die Änderungsnachverfolgung und die Lösung von Mergekonflikten erheblich verbessert, indem ordnungsgemäß formatierte JSON-Dateien verwendet werden.

Jede Seite, jedes Visual, jede Textmarke usw. befindet sich in einer separaten einzelnen Datei innerhalb einer Ordnerstruktur. Dieses Format eignet sich hervorragend für die Konfliktlösung bei Co-Entwicklung.

Im Gegensatz zum PBIR-Legacy-Format (report.json) ist PBIR ein öffentlich dokumentiertes Format, das Änderungen von Anwendungen außerhalb von Power BI unterstützt. Jede Datei verfügt über ein öffentliches JSON-Schema, mit dem nicht nur die Datei dokumentiert, sondern auch ermöglicht wird, dass Code-Editoren wie Visual Studio Code während der Bearbeitung eine Syntaxüberprüfung durchführen.

Einige der mit dem PBIR-Format jetzt möglichen Szenarios sind:

• Kopieren von Seiten, Visuals und Textmarken zwischen Berichten
• Sicherstellen von Konsistenz bei einer Gruppe von Visuals auf allen Seiten durch Kopieren und Einfügen der Visualdateien
• Einfaches Suchen und Ersetzen in mehreren Berichtsdateien gleichzeitig
• Anwenden einer Batchbearbeitung auf alle Visuals mithilfe eines Skripts (z. B. Ausblenden von Filtern auf Visualebene)

Aktivieren der Previewfunktion für das PBIR-Format

Das Speichern von Power BI-Projekten im PBIR-Format befindet sich derzeit in der Vorschau. Vor der Verwendung müssen Sie das Feature erst bei den Previewfunktionen für Power BI Desktop aktivieren:

Navigieren Sie zu Datei > Optionen und Einstellungen > Optionen > Previewfunktionen, und aktivieren Sie das Kontrollkästchen neben Store reports using enhanced metadata format (PBIR) (Berichte im erweiterten Metadatenformat (PBIR) speichern).

Speichern als Projekt im PBIR-Format

Wenn die Previewfunktion für das PBIR-Format aktiviert ist, wird Ihr Bericht beim Speichern eines Projekts in einem Ordner mit dem Namen \definition innerhalb des Berichtsordners gespeichert:

Weitere Informationen zur PBIR-Ordnerstruktur finden Sie unter diesem Link.

Konvertieren eines bereits vorhandenen PBIP ins PBIR-Format

Wenn Sie bereits über ein PBIP im PBIR-Legacy-Format verfügen, können Sie dieses wie folgt ins PBIR-Format konvertieren:

1. Öffnen Sie das PBIP in Power BI Desktop.

2. Stellen Sie sicher, dass die Previewfunktion aktiviert ist.

3. Speichern Sie das Projekt. Es wird eine Eingabeaufforderung angezeigt, in der Sie dazu aufgefordert werden, ein Upgrade auf das PBIR-Format durchzuführen.

4. Wählen Sie Upgrade aus.

   

   Wichtig

   Nachdem Sie ein Upgrade auf das PBIR-Format durchgeführt haben, können Sie nicht mehr zum PBIR-Legacy-Format zurückkehren. Wenn Sie glauben, dass Sie möglicherweise zum PBIR-Legacy-Format zurückkehren möchten, speichern Sie zuerst eine Kopie Ihrer PBIP-Dateien.

Die bestehende PBIR-Legacy-Datei (report.json) wird durch den Ordner \definition ersetzt, der die PBIR-Darstellung des Berichts enthält.

Wenn Sie auswählen, dass Sie das aktuelle Format beibehalten möchten, fordert Power BI Desktop Sie nicht erneut zur Durchführung eines Upgrades auf.

Veröffentlichen eines PBIR-Berichts im Power BI-Dienst

Während der Vorschauphase können Berichte im PBIR-Format nur über die Git-Integration von Fabric veröffentlicht werden. Dies umfasst das Verbinden des Arbeitsbereichs mit einem Git-Repository und das Pushen des PBIR-Berichts in dieses Repository, das dann zu einem späteren Zeitpunkt mit dem Dienstarbeitsbereich synchronisiert werden kann.

Wenn Sie einen bestehenden Bericht im Dienst in das PBIR-Format konvertieren möchten, führen Sie die folgenden Schritte aus:

1. Verbinden Sie Ihren Arbeitsbereich mit Git.
2. Klonen Sie das Git-Repository in Ihr lokales Dateisystem.
3. Öffnen Sie den Bericht in Power BI Desktop, indem Sie die Datei definition.pbir öffnen.
4. Speichern Sie den Bericht, und wählen Sie aus, dass ein Upgrade auf das PBIR-Format durchgeführt werden soll.
5. Committen und synchronisieren Sie die Änderungen in Git.
6. Aktualisieren Sie den Arbeitsbereich mit den neuesten Änderungen aus Git.

PBIR-Ordner und -Dateien

Die Berichtsdefinition wird im Ordner definition\ mit der folgenden Struktur gespeichert:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

Datei/Ordner	Erforderlich	Beschreibung
bookmarks\	No	Ordner mit allen Textmarkendateien des Berichts
── [bookmarkName].bookmark.json	No	Metadaten zu Textmarken, z. B. Zielvisuals und Filter. Weitere Informationen finden Sie im Schema.
── bookmarks.json	No	Metadaten zu Textmarken, z. B. Reihenfolge der Textmarken und Gruppen. Weitere Informationen finden Sie im Schema.
pages\	Ja	Ordner mit allen Seiten des Berichts
── [pageName]\	Ja	Ein Ordner pro Seite
──── visuals\	No	Ordner mit allen Visuals auf der Seite
────── [visualName]\	No	Ein Ordner pro Visual
──────── mobile.json	No	Metadaten zum mobilen Layout von Visuals, z. B. Position und Formatierung auf mobilen Geräten. Weitere Informationen finden Sie im Schema.
──────── visual.json	Ja	Metadaten zum Visual, z. B. Position und Formatierung sowie Abfragen. Weitere Informationen finden Sie im Schema.
──── page.json	Ja	Metadaten zur Seite, z. B. Filter und Formatierung auf Seitenebene. Weitere Informationen finden Sie im Schema.
── pages.json	No	Metadaten zu Seiten, z. B. Reihenfolge der Seiten und aktive Seite. Weitere Informationen finden Sie im Schema.
version.json	Ja	Neben anderen Faktoren ist die PBIR-Dateiversion entscheidend dafür, welche erforderlichen Dateien geladen werden. Weitere Informationen finden Sie im Schema.
reportExtensions.json	No	Berichtserweiterungen, z. B. Measures auf Berichtsebene. Weitere Informationen finden Sie im Schema.
report.json	Ja	Metadaten zum Bericht, z. B. Filter und Formatierung auf Berichtsebene. Weitere Informationen finden Sie im Schema.

PBIR-Namenskonvention

Standardmäßig wird für die Seiten, Visuals und Textmarken der jeweilige Berichtsobjektname als Datei- oder Ordnername verwendet. Die Objektnamen sind standardmäßig eindeutige Bezeichner mit 20 Zeichen, z. B. „90c2e07d8e84e7d5c026“.

Das Umbenennen der Datei oder des Ordners wird unterstützt, und Power BI behält den ursprünglichen Dateinamen beim Speichern bei. Das Umbenennen in der Eigenschaft „name“ innerhalb der einzelnen JSON-Dateien wird zwar ebenfalls unterstützt, kann jedoch dazu führen, dass externe Verweise (sowohl innerhalb als auch außerhalb des Berichts) nicht mehr funktionieren. Sowohl der Objektname als auch der Datei- bzw. Ordnername müssen aus mindestens einem Wortzeichen (Buchstaben, Ziffern, Unterstriche) oder Bindestrich bestehen.

PBIR-JSON-Schemas

Jede PBIR-JSON-Datei enthält eine JSON Schema-Deklaration oben im Dokument. Diese Schema-URL ist öffentlich zugänglich und kann verwendet werden, um mehr über die verfügbaren Eigenschaften und Objekte für jede Datei zu erfahren. Darüber hinaus sind IntelliSense und eine Überprüfung beim Bearbeiten mit Code-Editoren wie Visual Studio Code integriert.

Mit der Schema-URL wird auch die Version des Dokuments definiert. Es wird erwartet, dass diese sich mit der Weiterentwicklung der Berichtsdefinition ändert.

Alle JSON-Schemas werden unter diesem Link veröffentlicht.

Externe Änderungen an PBIR-Dateien

Sie können die PBIR-JSON-Dateien mit einem Code-Editor wie Visual Studio Code oder einem externen Tool bearbeiten, solange die Dateien dem JSON-Schema entsprechen. Die Verwendung eines falschen Eigenschaftsnamens oder -typs kann leicht direkt in Visual Studio Code erkannt werden:

Externe Änderungen an PBIR-Inhalten können zu Fehlern beim erneuten Öffnen der Dateien in Power BI Desktop führen. Es kann sich dabei um zwei Arten von Fehlern handeln:

Blockierende Fehler verhindern, dass Power BI Desktop den Bericht öffnet. Diese Fehler helfen beim Identifizieren des Problems und der fehlerhaften Datei, die vor dem erneuten Öffnen korrigiert werden muss:

Fehler wie ein ungültiges Schema oder fehlende erforderliche Eigenschaften werden als blockierende Fehler angesehen. Diese Fehler können leicht identifiziert werden, indem Sie die Datei in Visual Studio Code öffnen und die Schemafehler überprüfen.

Nicht blockierende Fehler verhindern nicht, dass Power BI Desktop den Bericht öffnet, und werden automatisch gelöst.

Fehler wie eine ungültige activePageName-Konfiguration sind Beispiele für nicht blockierende Fehler, die automatisch behoben werden. Die Warnung ist erforderlich, um Ihnen die Möglichkeit zu geben, das Speichern des Berichts mit der automatischen Korrektur zu vermeiden und so einen potenziellen Verlust vorgenommener Änderungen zu verhindern.

Häufige PBIR-Fehler

Szenario:Nach dem Umbenennen von Visual- oder Seitenordnern wird mein Visual oder meine Seite beim Öffnen des Berichts nicht mehr angezeigt.

Lösung: Überprüfen Sie, ob der Name der Namenskonvention entspricht. Wenn nicht, ignoriert Power BI Desktop die Datei oder den Ordner und behandelt die Dateien als private Benutzerdateien.

Szenario:Neue Berichtsobjekte werden anders benannt als andere. Die meisten Seitenordner sind beispielsweise nach dem Schema „ReportSection0e71dafbc949c0853608“ benannt, ein paar wenige jedoch nach dem Schema „1b3c2ab12b603618070b“.

Lösung: Beim PBIR-Format gilt für alle Objekte eine neue Namenskonvention, die jedoch nur auf neue Objekte angewendet wird. Wenn Sie einen bereits vorhandenen Bericht als PBIP speichern, müssen die aktuellen Namen beibehalten werden, um zu verhindern, dass Verweise nicht mehr funktionieren. Wenn eine konsistente Benennung gewünscht ist, ist eine Umbenennung in Batches mithilfe eines Skripts zulässig.

Szenario:Ich habe eine Textmarkendatei kopiert, und beim Speichern wurde der Großteil der Textmarkenkonfiguration gelöscht.

Lösung: Dieses Verhalten ist beabsichtigt. Bei Textmarken in Berichten wird der Zustand einer Berichtsseite mitsamt aller Visuals erfasst. Da der erfasste Zustand von einer anderen Berichtsseite mit anderen Visuals stammt, werden alle ungültigen Visuals aus der Textmarkenkonfiguration entfernt. Wenn Sie auch die abhängigen Visuals und Seiten kopieren, wird die Konfiguration der Textmarke beibehalten.

Szenario:Ich habe einen Seitenordner aus einem anderen Bericht kopiert, und nun wird folgende Fehlermeldung angezeigt: „Values for the ‚pageBinding.name‘ property must be unique.“ (Die Werte für die Eigenschaft ‚pageBinding.name‘ müssen eindeutig sein.)

Lösung: Das pageBinding-Objekt ist erforderlich, damit QuickInfos zu Drillthroughs und Seiten unterstützt werden. Da auf diese Objekte möglicherweise von anderen Seiten verwiesen wird, muss ihr Name innerhalb des Berichts eindeutig sein. Weisen Sie auf der neu kopierten Seite einen eindeutigen Wert zu, um den Fehler zu beheben. Nach Juni 2024 stellt diese Situation kein Problem mehr dar, da die Namen von pageBinding-Objekten standardmäßig GUIDs sind.

Überlegungen zum und Einschränkungen beim PBIR-Format

Das PBIR-Format befindet sich derzeit in der Vorschau. Berücksichtigen Sie Folgendes:

• Diensteinschränkungen
  • Das Integrieren mit Power BI-Apps ist nicht möglich.
  • Das Herunterladen im PBIX-Format ist nicht möglich.
  • Das Exportieren in PPTX- oder PDF-Dateien ist nicht möglich.
  • Das Integrieren in Abonnements ist nicht möglich.
  • Das Bereitstellen mit Bereitstellungspipelines ist nicht möglich.
  • Mobile Layouts werden nicht angewendet.
  • Das Speichern als Kopie ist nicht möglich.
  • Das Veröffentlichen über Power BI Desktop ist nicht möglich.
  • Das Hochladen in einen Arbeitsbereich im PBIX-Format ist nicht möglich.
  • Das Verwenden in Power BI Embedded ist nicht möglich.
• Bei großen Berichten mit mehr als 500 Dateien treten bei der Dokumenterstellung Leistungsprobleme auf (das Anzeigen von Berichten ist hiervon nicht betroffen), unter anderem bei Folgendem:
  • Speichern in Power BI Desktop
  • Synchronisierung in der Git-Integration von Fabric
• Nach dem Konvertieren eines Berichts vom PBIR-Legacy-Format ins PBIR-Format ist ein Wechsel zurück nicht mehr möglich.
• Beim Konvertieren einer PBIP-Datei in eine PBIX-Datei mithilfe des Features „Speichern unter“ wird der PBIR-Bericht in die PBIX-Datei eingebettet, wodurch alle Einschränkungen für das PBIR-Format auch für die PBIX-Datei gelten.

Die folgenden PBIR-Größenbeschränkungen werden vom Dienst erzwungen:

• Maximal 1.000 Seiten pro Bericht
• Maximal 300 Visuals pro Seite
• Maximal 5 MB pro Textmarkendatei
• Maximal 1 MB pro Datei
• Maximal 1.000 Ressourcenpaketdateien pro Bericht
• Maximale Größe von 300 MB für alle Ressourcenpaketdateien
• Maximale Größe von 20 MB für alle Berichtsdateien

Während der öffentlichen Vorschauphase verwenden die Git-Integration von Fabric und die Fabric-REST-APIs beim Exportieren der Berichtsdefinitionen weiterhin das PBIR-Legacy-Format (report.json). Wenn beim Importieren des Berichts in Fabric jedoch das PBIR-Format verwendet wird, beginnen beide Features mit dem Exportieren der Berichtsdefinition im PBIR-Format.

Zugehöriger Inhalt

• Semantikmodellordner eines Power BI Desktop-Projekts
• Power BI Desktop-Projekte