Složka projektu sestavy Power BI Desktopu

Tento článek popisuje soubory a podsložky ve složce Sestava projektu Microsoft Power BI Desktop. Zde uvedené soubory a podsložky představují sestavu Power BI. V závislosti na vašem projektu může složka sestavy obsahovat:

1 – Tento soubor je povinný.
2 – Tento soubor je vyžadován pro formát PBIR-Legacy.
3 – Tento soubor je povinný pro formát PBIR.

Ne každá složka sestavy projektu obsahuje všechny soubory a podsložky uvedené zde.

Soubory sestav

.pbi\localSettings.jszapnuto

Obsahuje nastavení sestavy, která platí jenom pro aktuálního uživatele a místní počítač. Měla by být zahrnuta v gitIgnore nebo jiných vyloučeních správy zdrojového kódu. Git ve výchozím nastavení tento soubor ignoruje.

Další informace najdete v dokumentu schématu localSettings.json.

CustomVisuals\

Podsložka, která obsahuje metadata pro vlastní vizuály v reportu. Power BI podporuje tři druhy vlastních vizuálů:

  • Vizuály organizačního úložiště – Organizace můžou schválit a nasadit vlastní vizuály do Power BI pro svou organizaci. Další informace najdete v úložišti organizace.
  • Vizuály Power BI v AppSource – označované také jako "Veřejné vlastní vizuály". Tyto vizuály jsou k dispozici v Microsoft AppSource. Vývojáři sestav mohou tyto vizuály nainstalovat přímo z Power BI Desktopu.
  • Soubory vlastních vizuálů – označuje se také jako "Soukromé vlastní vizuály". Soubory lze do sestavy načíst nahráním balíčku pbiviz.

Do složky CustomVisuals se načtou jenom soukromé vlastní vizuály. Power BI Desktop automaticky načítá vizualizace AppSource a vizualizace organizace.

RegisteredResources\

Podsložka, která obsahuje soubory prostředků specifické pro sestavu a načtené uživatelem, jako jsou vlastní motivy, obrázky a vlastní vizuály (soubory „pbiviz“).

Vývojáři zodpovídají za zde uvedené soubory a podporují se změny. Můžete například změnit soubor a po restartování Power BI Desktopu se nový soubor načte do sestavy. Tato složka může odblokovat některé užitečné scénáře, například:

  • Vytváření vlastních motivů mimo Power BI Desktop pomocí veřejného schématu
  • Použití dávkových změn změnou souboru prostředků na více sestavách Můžete například přepínat firemní vlastní motiv, měnit mezi světlými a tmavými motivy a měnit obrázky loga.

Každý soubor prostředků musí mít odpovídající záznam v souboru report.json. Úpravy souborů RegisteredResources jsou podporovány pouze pro již načtené prostředky, které způsobují, že Power BI Desktop zaregistruje prostředek v report.json.

semanticModelDiagramLayout.json

Obsahuje diagramy datového modelu popisující strukturu sémantického modelu, který je spojen se zprávou. Tento soubor nepodporuje externí úpravy.

definition.pbir

Obsahuje celkovou definici sestavy a klíčová nastavení. Tento soubor obsahuje také odkaz na sémantický model používaný sestavou. Power BI Desktop může otevřít soubor PBIR přímo, stejně jako při otevření souboru PBIP. Otevření souboru PBIR zároveň otevře sémantický model, pokud existuje relativní odkaz pomocí byPath.

Příklad definice.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"
    }    
  }
}

Definice obsahuje vlastnost datasetReference, která se odkazuje na sémantický model použitý v sestavě. Odkaz může být buď:

byPath – Určuje relativní cestu ke sémantické složce modelu. Absolutní cesty nejsou podporovány. Lomítko (/) se používá jako oddělovač složek. Když se použije, Power BI Desktop také otevře sémantický model v plném režimu úprav.

byConnection – Určuje připojení k sémantickému modelu v pracovním prostoru Fabric pomocí připojovacího řetězce. Když použijete byConnection odkaz, Power BI Desktop neotevře sémantický model v režimu úprav.

S použitím byConnection odkazu musí být zadány následující vlastnosti:

Nemovitost Popis
připojovací řetězec Připojovací řetězec odkazující na sémantický model v pracovním prostoru Fabric.

Příklad použití 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]"
    }
  }
}

Při nasazování sestavy prostřednictvím rozhraní Fabric REST API stačí zadat pouze vlastnost semanticmodelid. Například:

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

Důležité

Při nasazování sestavy prostřednictvím Fabric REST API musíte použít byConnection odkazy. Nemělo by se zaměňovat s režimem úložiště sémantického modelu, jako je DirectQuery. V sestavě datasetReference se pouze specifikuje, ke kterému sémantickému modelu se report připojuje, nedefinuje, jak tento model ukládá nebo přistupuje k datům.

Více souborů *.pbir

Když sémantický model a sestava sdílejí stejný pracovní prostor, Fabric Git Integration vždy exportuje definice s odkazem byPath na sémantický model. Pokud chcete vynutit, aby se sestava otevřela pomocí live connect (například pro práci s metrikami na úrovni sestavy), můžete mít více *.pbir souborů, například jeden s připojením byPath a druhý s připojením byConnection. Integrace Fabric Gitu zpracovává pouze soubor definition.pbir a ignoruje všechny ostatní soubory *.pbir. Tyto soubory však mohou existovat ve stejném úložišti.

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

Soubor definition.pbir také určuje podporované formáty definic sestav prostřednictvím vlastnosti 'version'.

Verze Podporované formáty
1.0 Definice sestavy musí být uložena v souboru report.json jako formát PBIR-Legacy.
4.0 nebo vyšší Definici sestavy lze uložit jako soubor PBIR-Legacy (soubor report.json) nebo PBIR (\definition folder).

Další informace naleznete v dokumentu schématu definition.pbir.

mobileState.json

Obsahuje nastavení vzhledu a chování zprávy při vykreslování na mobilním zařízení. Tento soubor nepodporuje externí úpravy.

report.json

Tento soubor obsahuje definici sestavy ve formátu Power BI Report Legacy (PBIR-Legacy) a nepodporuje externí úpravy.

definice\ složka

Tato složka je dostupná jenom v případě, že je projekt Power BI uložený ve formátu rozšířené sestavy Power BI (PBIR). Nahradí soubor report.json.

.platforma

Soubor platformy Fabric, který obsahuje vlastnosti nezbytné pro navázání a udržování propojení mezi položkami Fabric a Gitem.

Další informace najdete v tématu Integrace Gitu automaticky generovaných systémových souborů.

Formát PBIR

Ukládání souborů projektu Power BI (PBIP) pomocí rozšířeného formátu sestav Power BI (PBIR) výrazně zlepšuje sledování změn a řešení konfliktů při slučování pomocí správně formátovaných souborů JSON.

Snímek obrazovky přátelských rozdílů PBIR.

Každá stránka, vizuál, záložka atd., je uspořádaná do samostatného jednotlivého souboru ve struktuře složek. Tento formát je ideální pro řešení konfliktů při společném vývoji.

Snímek obrazovky přátelské složky PBIR

Na rozdíl od PBIR-Legacy (report.json) je PBIR veřejně zdokumentovaný formát, který podporuje úpravy z aplikací mimo Power BI. Každý soubor má veřejné schéma JSON, které nejen dokumentuje soubor, ale také umožňuje editorům kódu, jako je Visual Studio Code, provádět ověřování syntaxe při úpravách.

Mezi možné scénáře, které jsou teď dostupné v PBIR, patří:

  • Zkopírujte stránky, vizuály nebo záložky v rámci sestav.
  • Zajistěte konzistenci sady vizuálů na všech stránkách zkopírováním a vložením souborů vizuálu.
  • Snadné vyhledání a nahrazení napříč několika soubory sestav.
  • Použití dávkové úpravy ve všech vizuálech pomocí skriptu (například skrytí filtrů na úrovni vizuálů)

Uložit jako projekt pomocí PBIR

Když uložíte projekt pomocí PBIR, sestava se uloží do složky s názvem \definition uvnitř složky report:

Snímek obrazovky se složkou definice uvnitř složky PBIP sestavy

Přečtěte si další informace o struktuře složek PBIR.

Složka a soubory PBIR

Definice sestavy je uložena do definition\ složky s následující strukturou:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json
Soubor nebo složka Požadováno Popis
záložky\ Ne Složka, která obsahuje všechny soubory záložek sestavy.
[bookmarkName].bookmark.json Ne Metadata záložek, jako jsou cílené vizualizace a filtry.
Další informace o schématu
── záložky.json Ne Metadata záložek, jako je pořadí záložek a skupiny.
Další informace o schématu
stránky\ Ano Složka obsahující všechny stránky sestavy
[pageName]\ Ano Jedna složka na stránku.
──── vizuály Ne Složka, ve které jsou všechny vizuály stránky.
────── [visualName]\ Ne Jedna složka na vizuál
─────── mobile.json Ne Metadata rozložení vizuálu pro mobilní zařízení, například umístění mobilního zařízení a formátování
Další informace o schématu
─────── visual.json Ano Vizuální metadata, například umístění a formátování, dotaz.
Další informace o schématu
page.json Ano Metadata stránek, jako jsou filtry na úrovni stránek a formátování.
Další informace o schématu
–– pages.json Ne Metadata stránek, například pořadí stránek a aktivní stránka.
Další informace o schématu
version.json Ano Verze souboru PBIR mimo jiné určuje požadované soubory, které se mají načíst.
Další informace o schématu
reportExtensions.json Ne Rozšíření sestav, jako jsou míry na úrovni sestavy.
Další informace o schématu
report.json Ano Metadata sestav, jako jsou filtry na úrovni sestavy a formátování.
Další informace o schématu

Důležité

Některé soubory metadat sestavy, například visual.json nebo bookmarks.json, lze uložit s datovými hodnotami z sémantického modelu. Pokud například použijete filtr na vizuál pro pole "Společnost" = "Contoso", hodnota Contoso se zachová jako součást metadat. To platí také pro jiné konfigurace, jako jsou výběry průřezů, šířka vlastních sloupců matice a formátování pro konkrétní řady.

Pravidla pojmenování PBIR

Všechny názvy uvnitř hranatých závorek ([]) v předchozí tabulce se řídí výchozími konvencemi pojmenování, ale dají se přejmenovat na uživatelsky přívětivější názvy. Ve výchozím nastavení používají stránky, vizuály a záložky název reportového objektu jako název souboru nebo složky. Tyto názvy objektů jsou zpočátku jedinečný identifikátor 20 znaků, například 90c2e07d8e84e7d5c026.

Snímek obrazovky s vlastností názvu PBIR

Přejmenování vlastnosti 'name' v rámci každého souboru JSON je podporováno, ale může narušit externí odkazy uvnitř i vně sestavy. Název objektu nebo název souboru nebo složky musí obsahovat jeden nebo více znaků slova (písmena, číslice, podtržítka) nebo pomlčky.

Po přejmenování souborů nebo složek PBIR je nutné restartovat Power BI Desktop. Po restartování zachová Power BI Desktop při ukládání původní názvy souborů nebo složek.

Zkopírování názvu objektu sestavy

Každý objekt ve zprávě je uložený v samostatné složce nebo souboru, ale název složky není vždy zřejmý. Abyste to usnadnili, můžete zkopírovat název libovolného názvu objektu sestavy (včetně stránek, vizuálů, záložek a filtrů) přímo z Power BI do schránky.

Snímek obrazovky sestavy se šipkou ukazující z jednoho z vizuálních prvků na název odpovídajícího souboru.

  1. Přejděte na Možnosti souboru > a nastavení > Nastavení Sestava Objekty sestavy > a povolte kopírování názvů objektů při kliknutí pravým tlačítkem myši na nastavení objektů sestavy. Stačí to udělat jenom jednou.

    Snímek obrazovky s nastavením sestavy objektů sestavy

  2. Klikněte pravým tlačítkem na libovolný objekt sestavy a vyberte Kopírovat název objektu.

    Snímek obrazovky reportu plochy s vybraným názvem objektu ke kopírování

Pomocí názvu objektu zkopírovaného do schránky ho můžete snadno zadat do vyhledávacího panelu Průzkumníka Windows nebo editoru Visual Studio Code a vyhledat nebo identifikovat název objektu ve složce PBIR.

Snímek obrazovky s panelem hledání s názvem objektu

Schémata PBIR Json

Každý soubor JSON PBIR obsahuje deklaraci schématu JSON v horní části dokumentu. Tato adresa URL schématu je veřejně přístupná a dá se použít k získání dalších informací o dostupných vlastnostech a objektech pro každý soubor. Kromě toho poskytuje integrovanou technologii IntelliSense a ověřování při úpravách pomocí editorů kódu, jako je Visual Studio Code.

Snímek obrazovky s popisem výzvy PBIR JSON Schema

Adresa URL schématu také definuje verzi dokumentu, u které se očekává, že se při vývoji definice sestavy změní.

Tady jsou publikována všechna schémata JSON.

Poznámky PBIR

Poznámky můžete zahrnout jako páry název-hodnota v definici sestavy pro každou visual, page a report. I když Power BI Desktop tyto poznámky ignoruje, můžou být cenné pro externí aplikace, jako jsou skripty.

Můžete například zadat výchozí stránku pro sestavu v report.json souboru, kterou pak může využít skript nasazení.

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

Externí změny souborů PBIR

Podporované soubory PBIR JSON můžete upravovat například v editoru kódu Visual Studio Code nebo v jiném externím nástroji, zatímco projekt zůstává otevřený v aplikaci Power BI Desktop. Když soubory uložíte, Power BI Desktop zjistí změny a zobrazí banner Použít externí změny. Vyberte možnost Použít externí změny, aby se znovu načetla definice sestavy bez zavření a opětovného otevření projektu.

Před externí úpravou souborů PBIR uložte všechny změny v Power BI Desktopu. Pokud Power BI Desktop při použití externích změn obsahuje neuložené změny, upozorní vás, že neuložené změny budou přepsány. Kompletní pracovní postup a omezení najdete v tématu Úprava souborů PBIP mimo Power BI Desktop.

Soubory PBIR musí odpovídat jejich schématům JSON. VS Code identifikuje problémy, jako je nepodporovaný název vlastnosti nebo nesprávný typ vlastnosti:

Snímek obrazovky s výzvou k ověření schématu JSON PBIR

Externí změny obsahu PBIR můžou způsobit chyby při použití změn nebo otevření souborů v Power BI Desktopu. Tyto chyby můžou mít dva typy:

Blokující chyby brání aplikaci Power BI Desktop v načtení změn sestavy. Tyto chyby identifikují problém a soubor, který musíte opravit, než změny znovu použijete:

Snímek obrazovky s chybou blokování PBIR promptu

Chyby, jako je neplatné schéma nebo chybějící požadované vlastnosti, blokují chyby. Pokud chcete tyto chyby identifikovat, otevřete soubor ve VS Code a zkontrolujte zprávy ověření schématu.

Neblokující chyby nebrání tomu, aby Power BI Desktop otevřel sestavu, a jsou automaticky vyřešeny.

Snímek obrazovky s chybou odblokování výzvy PBIR

Neplatná konfigurace activePageName je příkladem neblokující chyby, kterou Power BI Desktop automaticky opraví. Upozornění vám poskytne příležitost zkontrolovat opravu před uložením sestavy a přepsáním externí definice.

Běžné chyby PBIR

Scénář:Po přejmenování vizuálů nebo složek stránek se při otevření reportu už nezobrazí ani můj vizuál, ani stránka.

Řešení: Ověřte, jestli název splňuje zásady vytváření názvů. Pokud ne, Power BI Desktop soubor nebo složku ignoruje a považuje ho za soukromé uživatelské soubory.

Scénář:Nové objekty sestavy se nazývají jinak než ostatní. Například většina složek stránek má název ReportSection0e71dafbc949c0853608, zatímco několik z nich má název 1b3c2ab12b603618070b.

Řešení: PBIR přijala novou konvenci pojmenování pro každý objekt, ale vztahuje se pouze na nové objekty. Když uložíte existující sestavu jako PBIP, aktuální názvy se musí zachovat, aby nedošlo k přerušení odkazů. Pokud chcete mít konzistenci, je povoleno použít skript pro dávkové přejmenování.

Scénář:Zkopíroval(a) jsem soubor záložky a po uložení se většina konfigurace záložky odstranila.

Řešení: Toto chování je záměrné, záložky sestavy zachycují stav stránky sestavy spolu se všemi jejími vizuálními prvky. Vzhledem k tomu, že zaznamenaný stav pochází z jiné stránky sestavy s odlišnými vizualizacemi, všechny neplatné vizualizace se z konfigurace záložek odeberou. Pokud také zkopírujete závislé vizuály a stránku, záložka zachová svou konfiguraci.

Scénář:Zkopíroval(a) jsem složku stránky z jiné sestavy a narazil(a) na chybu, která uvádí, že hodnoty pro vlastnost 'pageBinding.name' musí být jedinečné.

Řešení: Objekt pageBinding je nezbytný pro podporu podrobné analýzy a popisů stránek. Vzhledem k tomu, že na ně můžou odkazovat jiné stránky, musí být název v rámci zprávy jedinečný. Na nově zkopírované stránce přiřaďte jedinečnou hodnotu k vyřešení chyby. Po červnu 2024 už tato situace není problém, protože název pageBinding je ve výchozím nastavení identifikátor GUID.

Převést stávající zprávu na PBIR

PBIR je obecně dostupný a je výchozím formátem sestavy. Sestavy, které používají PBIR-Legacy, můžete stále otevřít v aplikaci Power BI Desktop a ve službě Power BI. Když upravíte a uložíte sestavu PBIR-Legacy, Power BI ji automaticky a na pozadí převede na PBIR.

Před převodem Power BI vytvoří zálohu sestavy:

  • Power BI Desktop uchovává zálohu po dobu 30 dnů v jednom z následujících umístění:
    • Verze Microsoft Storu: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Verze spustitelného instalačního programu: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • služba Power BI uchovává zálohu PBIR-Legacy po dobu 28 dnů. Chcete-li ji obnovit, otevřete v pracovním prostoru možnost Nastavení sestavy a vyberte Obnovit jako PBIR-Legacy. Toto zálohování se vytvoří pouze pro sestavy převedené přímo v služba Power BI.

Obnovení zálohy PBIR-Legacy nezabrání další konverzi. Pokud chcete sestavu zachovat ve formátu PBIR-Legacy, neupravujte ji v služba Power BI nebo použijte verzi Power BI Desktop vydané před zářím 2026.

Aspekty a omezení PBIR

Mějte na paměti následující aspekty a omezení:

  • Automatické filtry vizuálů se uloží do souboru PBIR visual.json až poté, co bylo podokno filtru alespoň jednou rozšířeno během úpravy sestavy.
  • Pokud Power BI při úpravách a uložení nepřevedí sestavu PBIR-Legacy na PBIR, došlo při převodu k problému s produktem. Vytvořte žádost o podporu pro nahlášení problému.

Omezení na velikost PBIR, která jsou službou vynucena:

  • Maximálně 1 000 stránek na zprávu
  • Maximálně 1000 vizuálů na stránku
  • Maximálně 1 000 souborů balíčků prostředků na sestavu.
  • Maximální velikost 300 MB pro všechny soubory balíčků prostředků.
  • Maximální velikost všech souborů sestav dohromady je 300 MB.

Důležité

Pokud dosáhnete výše uvedených limitů, může být dobré zvážit optimalizaci reportu. Podívejte se na dokument Optimalizace Power BI.

Integrace Fabric s Gitem a rozhraní REST API Fabric exportují definice sestav pomocí PBIR.

Související obsah

  • Poslední aktualizace v