Priečinok zostavy projektu aplikácie Power BI Desktop

Tento článok popisuje súbory a podpriečinky v priečinku Report projektu Microsoft Power BI Desktop. Súbory a podpriečinky v tomto priečinku predstavujú zostavu Power BI. V závislosti od projektu môže priečinok zostavy obsahovať položky:

1 - Tento súbor je povinný.
2 – Tento súbor sa vyžaduje v PBIR-Legacy formáte.
3 – Tento súbor sa vyžaduje pre formát PBIR.

Nie každý priečinok zostavy projektu obsahuje všetky súbory a podpriečinky popísané tu.

Súbory správ

.pbi\localSettings.json

Obsahuje nastavenia zostavy, ktoré sa vzťahujú len na aktuálneho používateľa a lokálny počítač. Mala by sa zahrnúť do vylúčenia gitIgnore alebo iného vylúčenia správy zdrojov. Predvolene Git tento súbor ignoruje.

Ďalšie informácie nájdete v dokumente localSettings.json schému.

CustomVisuals\

Podpriečinok, ktorý obsahuje metaúdaje pre vlastné vizuály v zostave. Služba Power BI podporuje tri druhy vlastných vizuálov:

  • Vizuály ukladacieho priestoru organizácie – organizácie môžu schvaľovať a nasadzovať vlastné vizuály do služby Power BI pre svoju organizáciu. Ďalšie informácie nájdete v téme Obchod organizácie.
  • Vizuály Power BI z lokality AppSource – známe aj ako "Verejné vlastné vizuály". Tieto vizuály sú k dispozícii v službe Microsoft AppSource. Vývojári zostáv môžu tieto vizuály nainštalovať priamo z aplikácie Power BI Desktop.
  • Súbory vlastných vizuálov – známe aj ako "Súkromné vlastné vizuály". Súbory je možné načítať do zostavy nahratím balíka pbiviz.

Do priečinka CustomVisuals sa načítajú iba súkromné vlastné vizuály. Vizuály AppSource a Organization sa automaticky načítavajú pomocou aplikácie Power BI Desktop.

RegisteredResources\

Podpriečinok, ktorý obsahuje súbory prostriedkov špecifické pre danú zostavu a načítaný používateľom, ako sú napríklad vlastné motívy, obrázky a vlastné vizuály (súbory pbiviz).

Vývojári sú zodpovední za súbory v tomto článku a zmeny sú podporované. Môžete napríklad zmeniť súbor a po reštarte aplikácie Power BI Desktop sa nový súbor načíta do zostavy. Tento priečinok môže odblokovať niektoré užitočné scenáre, ako napríklad:

  • Vytváranie vlastných motívov mimo aplikácie Power BI Desktop pomocou verejnej schémy.
  • Použitie dávkových zmien zmenou súboru prostriedkov vo viacerých zostavách. Môžete napríklad prepnúť podnikový vlastný motív, zmeniť svetlý a tmavý motív a zmeniť obrázky loga.

Každý súbor prostriedkov musí mať zodpovedajúcu položku v súbore report.json. Úpravy súborov RegisteredResources sú podporované len pre už načítané prostriedky, čo spôsobí, že aplikácia Power BI Desktop zaregistruje prostriedok v report.json.

semanticModelDiagramLayout.json

Obsahuje diagramy dátového modelu popisujúce štruktúru sémantického modelu priradeného k zostave. Tento súbor nepodporuje externé úpravy.

definition.pbir

Obsahuje celkovú definíciu zostavy a jej základných nastavení. Tento súbor obsahuje aj odkaz na sémantický model, ktorý používa zostava. Aplikácia Power BI Desktop môže otvoriť súbor PBIR priamo, rovnako ako keby bola zostava otvorená zo súboru PBIP. Otvorením súboru PBIR sa okrem toho otvorí aj sémantický model, ak existuje relatívny odkaz pomocou funkcie byPath.

Príklad definition.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"
    }    
  }
}

Definícia obsahuje datasetReference vlastnosť , ktorá odkazuje na sémantický model použitý v zostave. Odkazom môže byť buď:

byPath – Určuje relatívnu cestu k cieľovému priečinku sémantického modelu. Absolútne cesty nie sú podporované. Lomka (/) sa používa ako oddeľovač priečinkov. Pri použití sa v aplikácii Power BI Desktop otvorí aj sémantický model v režime úplných úprav.

byConnection - Určuje pripojenie k sémantickému modelu v pracovnom priestore Fabric pomocou reťazca pripojenia. Pri použití odkazu byConnection power BI Desktop neotvorí sémantický model v režime úprav.

Pomocou odkazu byConnection je potrebné zadať nasledujúce vlastnosti:

Property Description
connectionString Reťazec pripojenia odkazujúci na sémantický model v pracovnom priestore Fabric.

Príklad použitia 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]"
    }
  }
}

Pri nasadzovaní zostavy prostredníctvom rozhrania REST API tkaniny stačí zadať vlastnosť semanticmodelid . Naprí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]"
    }
  }
}

Important

Pri nasadzovaní zostavy prostredníctvom rozhrania REST API služby Fabric musíte použiť byConnection odkazy. Toto by sa nemalo zamieňať s režimom úložiska sémantického modelu, ako je napríklad DirectQuery. Položka datasetReference v zostave určuje len to, ku ktorému sémantickému modelu sa zostava pripája, nedefinuje, ako daný model uloží alebo pristupuje k jeho údajom.

Viaceré súbory *.pbir

Keď sémantický model a zostava zdieľajú rovnaký pracovný priestor, integrácia Git služby Fabric vždy exportuje definície s odkazom byPath na sémantický model. Ak chcete vynútiť otvorenie zostavy v dynamickom pripojení (napríklad na prácu s mierkami na úrovni zostavy), môžete mať viacero *.pbir súborov, napríklad jeden s pripojením byPath a druhý s pripojením byConnection. Integrácia Git Fabric spracováva iba súbor definition.pbir a ignoruje všetky ostatné súbory *.pbir. Tieto súbory však môžu existovať súčasne v tom istom odkladacom priestore.

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

Súbor definition.pbir špecifikuje aj podporované formáty definícií zostavy prostredníctvom vlastnosti "version".

Version Podporované formáty
1.0 Definícia zostavy musí byť v súbore report.json uložená ako PBIR-Legacy.
4,0 alebo novšia verzia Definíciu zostavy je možné uložiť ako PBIR-Legacy (súborreport.json) alebo PBIR (priečinok \definícia).

Ďalšie informácie nájdete v dokumente definition.pbir schema.

mobileState.json

Obsahuje nastavenia vzhľadu a správania zostavy pri vykresľovaní v mobilnom zariadení. Tento súbor nepodporuje externé úpravy.

report.json

Tento súbor obsahuje definíciu zostavy vo formáte Staršej verzie zostavy Power BI (PBIR-Legacy) a nepodporuje externé úpravy.

definícia\ priečinok

Tento priečinok je k dispozícii len v prípade, že je projekt Power BI uložený pomocou formátu vylepšenej zostavy služby Power BI (PBIR). Nahradí súbor report.json .

.platform

Súbor platformy fabric, ktorý obsahuje vlastnosti dôležité pre vytvorenie a zachovanie prepojenia medzi položkami služby Fabric a službou Git.

Ďalšie informácie nájdete v téme Integrácia systému Git automaticky generované systémové súbory.

Formát PBIR

Uložením súborov projektu Power BI (PBIP) pomocou formátu vylepšenej zostavy služby Power BI (PBIR) sa výrazne zlepší sledovanie zmien a zlúčenie riešenia konfliktov pomocou správne naformátovaných súborov JSON.

Snímka obrazovky popisných rozdielov v PBIR.

Každá strana, vizuál, záložka atď. je rozdelená do samostatného, individuálneho súboru v rámci štruktúry priečinkov. Tento formát je ideálny na riešenie konfliktu v kódovej forme.

Snímka obrazovky popisného priečinka PBIR.

Na rozdiel od PBIR-Legacy (report.json), PBIR je verejne zdokumentovaný formát, ktorý podporuje úpravy z aplikácií mimo služby Power BI. Každý súbor má verejnú schému JSON, ktorá súbor nielen dokumentuje, ale tiež umožňuje editorom kódu, ako je napríklad Visual Studio Code, vykonávať overenie syntaxe počas úprav.

Niektoré z možných scenárov, ktoré sú teraz k dispozícii v PBIR, zahŕňajú:

  • Kopírovanie strán,vizuálov/záložiek medzi zostavami.
  • Skopírujte a prilepte súbory vizuálov naprieč všetkými stranami a zabezpečte konzistenciu množiny vizuálov na všetkých stranách.
  • Jednoduché vyhľadanie a nahradenie medzi viacerými súbormi zostáv.
  • Použitie dávkovej úpravy vo všetkých vizuáloch pomocou skriptu (napríklad skrytie filtrov na úrovni vizuálu)

Uložiť ako projekt pomocou PBIR

Keď uložíte projekt pomocou PBIR, zostava sa uloží do priečinka s názvom \definition v priečinku zostavy:

Snímka obrazovky znázorňujúca priečinok definície v rámci priečinka PBIP zostavy.

Ďalšie informácie o štruktúre priečinkov PBIR.

Priečinok a súbory PBIR

Definícia zostavy je uložená v priečinku definition\ s nasledujúcou štruktúrou:

├── 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/Folder Required Description
bookmarks\ No Priečinok uchováva všetky súbory záložiek zostavy.
── [názovZáložky].bookmark.json No Metaúdaje záložiek, ako sú napríklad cieľové vizuály a filtre.
Viac informácií na schema.
bookmarks.json No Metaúdaje záložiek, ako je napríklad poradie záložiek a skupiny.
Viac informácií na schema.
pages\ Yes Priečinok uchováva všetky strany zostavy.
── [názovStránky]\ Yes Jeden priečinok na stranu.
──── vizuály\ No Priečinok uchováva všetky vizuály strany.
────── [názovVizuálu]\ No Jeden priečinok na vizuál.
──────── mobile.json No Metaúdaje mobilného rozloženia vizuálu, ako je napríklad poloha na mobilnom zariadení a formátovanie.
Viac informácií na schema.
──────── visual.json Yes Metaúdaje vizuálu, napríklad pozícia a formátovanie, dotaz.
Viac informácií na schema.
page.json Yes metaúdaje strany, ako sú napríklad filtre na úrovni strany a formátovanie.
Viac informácií na schema.
pages.json No Metaúdaje strán, ako je napríklad poradie strán a aktívna strana.
Viac informácií na schema.
version.json Yes Verzia súboru PBIR okrem iného určuje požadované súbory, ktoré sa majú načítať.
Viac informácií na stránke schéma
reportExtensions.json No Rozšírenia zostavy, ako sú napríklad mierky na úrovni zostavy.
Viac informácií na stránke schéma
report.json Yes metaúdaje zostavy, ako sú napríklad filtre na úrovni zostavy a formátovanie.
Viac informácií na stránke schéma

Important

Niektoré súbory metaúdajov zostáv, ako napríklad visual.json alebo bookmarks.json, je možné uložiť s údajovými hodnotami zo sémantického modelu. Ak napríklad použijete filter na vizuál pre pole Company = Contoso, hodnota Contoso sa zachová ako súčasť metaúdajov. Vzťahuje sa to aj na iné konfigurácie, ako napríklad výbery rýchlych filtrov, šírku vlastných stĺpcov matice a formátovanie pre konkrétne rady.

Konvencia pomenovania PBIR

Všetky názvy v hranatých zátvorkách ([]) v predchádzajúcej tabuľke sa riadia predvolenou konvenciou pomenovania, ale možno ich premenovať na používateľsky prívetivejšie názvy. Strany, vizuály a záložky predvolene používajú ako názov objektu zostavy názov svojho súboru alebo priečinka. Tieto názvy objektov sú pôvodne 20-znakovým jedinečným identifikátorom, ako napríklad 90c2e07d8e84e7d5c026.

Snímka obrazovky s vlastnosťou názvu PBIR.

Premenovanie vlastnosti name v rámci každého súboru JSON je podporované, môže však poškodiť externé odkazy v rámci zostavy aj mimo ňou. Názov objektu a/alebo názov súboru/priečinka musí pozostávať z jedného alebo viacerých znakov slova (písmená, číslice, znaky podčiarknutia) alebo spojovníky.

Po premenovaní všetkých súborov alebo priečinkov PBIR musíte reštartovať aplikáciu Power BI Desktop. Po reštartovaní power BI Desktop pri ukladaní zachová pôvodné názvy súborov alebo priečinkov.

Kopírovanie názvu objektu zostavy

Každý objekt v zostave sa uloží do samostatného priečinka alebo súboru, ale názov priečinka nie je vždy zrejmý. Aby to bolo jednoduchšie, môžete skopírovať názov ľubovoľného názvu objektu zostavy (vrátane strán, vizuálov, záložiek a filtrov) priamo zo služby Power BI do schránky.

Snímka obrazovky zostavy so šípkou smerujúcou od jedného z vizuálov k názvu príslušného súboru.

  1. Prejdite na položky Súbor > Možnosti a nastavenia > Nastavenia > zostavy Objekty zostavy a po kliknutí pravým tlačidlom myši na nastavenie Objekty zostavy povoľte položku Kopírovať názvy objektov . Stačí to urobiť iba raz.

    Snímka obrazovky zobrazujúca nastavenia zostavy objektov zostavy.

  2. Kliknite pravým tlačidlom myši na ľubovoľný objekt zostavy a vyberte položku Kopírovať názov objektu.

    Snímka obrazovky znázorňujúca zostavu pracovnej plochy s vybratým názvom kopírovaného objektu.

Po skopírovaní názvu objektu do Schránky ho môžete jednoducho zadať do panela hľadania programu Windows Explorer alebo Visual Studio Code a vyhľadať alebo identifikovať názov objektu v priečinku PBIR.

Snímka obrazovky panela hľadania s názvom objektu.

Schémy PBIR Json

Každý súbor JSON PBIR obsahuje deklaráciu schémy JSON v hornej časti dokumentu. Táto URL adresa schémy je verejne prístupná a môže sa použiť na ďalšie informácie o dostupných vlastnostiach a objektoch každého súboru. Okrem toho poskytuje vstavanú funkciu IntelliSense a overenie pri úprave pomocou editorov kódu, ako je napríklad Visual Studio Code.

Snímka obrazovky zobrazujúca popis schémy PBIR JSON.

URL adresa schémy tiež definuje verziu dokumentu, ktorá sa má zmeniť, keď sa definícia zostavy bude vyvíjať.

Všetky schémy JSON sú zverejnené tu.

Anotácie PBIR

Komentáre môžete pridať ako páry názov-hodnota v rámci definície zostavy pre každú visualpage položku a report. Hoci Power BI Desktop tieto komentáre ignoruje, môže byť cenná pre externé aplikácie, ako sú napríklad skripty.

Môžete napríklad zadať predvolenú položkuPage pre zostavu report.json v súbore, ktorú potom môže využívať skript nasadenia.

{
  "$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é zmeny súborov PBIR

Podporované súbory PBIR JSON môžete upravovať v editore kódu, ako je napríklad Visual Studio Code alebo inom externom nástroji, kým projekt zostane otvorený v aplikácii Power BI Desktop. Keď súbory uložíte, Power BI Desktop zistí zmeny a zobrazí banner Použitie externých zmien. Výberom položky Použiť externé zmeny znova načítajte definíciu zostavy bez ukončenia a opätovného otvorenia projektu.

Pred externou úpravou súborov PBIR uložte všetky zmeny v aplikácii Power BI Desktop. Ak Power BI Desktop obsahuje neuložené zmeny pri použití externých zmien, upozorní vás, že neuložené zmeny sa prepíšu. Úplný pracovný postup a obmedzenia nájdete v téme Úprava súborov PBIP mimo aplikácie Power BI Desktop.

Súbory PBIR sa musia zhodovať s ich schémami JSON. VS Code identifikuje problémy, ako napríklad nepodporovaný názov vlastnosti alebo nesprávny typ vlastnosti:

Snímka obrazovky zobrazujúca výzvu na overenie schémy PBIR JSON.

Externé zmeny obsahu PBIR môžu spôsobiť chyby pri použití zmien alebo otváraní súborov v aplikácii Power BI Desktop. Tieto chyby môžu mať dva typy:

Zablokovanie chýb bráni Power BI Desktopu v načítavaní zmien zostavy. Tieto chyby identifikujú problém a súbor, ktorý musíte opraviť pred opätovním použitím zmien:

Snímka obrazovky zobrazujúca výzvu na chybu blokovania PBIR.

Chyby, ako je napríklad neplatná schéma alebo chýbajúce požadované vlastnosti, chyby blokujú. Ak chcete tieto chyby identifikovať, otvorte súbor v nástroji VS Code a skontrolujte overovacie správy schémy.

Chyby neblokovania nebránia aplikácii Power BI Desktop v otvorení zostavy a automaticky sa vyriešia.

Snímka obrazovky zobrazujúca chybu odblokovania v PBIR.

Neplatná activePageName konfigurácia je príkladom chyby nepoblokovania, ktorá sa Power BI Desktop automaticky opraví. Upozornenie vám poskytuje možnosť skontrolovať opravu ešte pred uložením zostavy a prepísať externú definíciu.

Bežné chyby v PBIR

Scenár:Po premenovaní názvov vizuálov alebo priečinkov stránok sa vizuál alebo strana už pri otvorení zostavy nezobrazí.

Riešenie: Overte, či je názov v súlade s konvenciou pomenovania. Ak sa tak nestane, Aplikácia Power BI Desktop súbor alebo priečinok ignoruje a narába s ním ako so súbormi súkromného používateľa.

Scenár:Nové objekty zostavy sú pomenované inak ako ostatné. Napríklad väčšina priečinkov stránok má názov "ReportSection0e71dafbc949c0853608", zatiaľ čo niektoré majú názov "1b3c2ab12b603618070b".

Riešenie: PBIR prijal novú konvenciu pomenovania pre každý objekt, ale tá sa vzťahuje len na nové objekty. Keď uložíte existujúcu zostavu ako PBIP, aktuálne názvy musia byť zachované, aby sa zabránilo porušeniu odkazov. Ak chcete dosiahnuť konzistentnosť, skript je povolený premenovaním dávky.

Scenár:Skopíroval som súbor záložiek a po uložení bola väčšina konfigurácie záložiek odstránená.

Riešenie: Toto správanie je zámerné, záložky zostavy zachytávajú stav strany zostavy spolu so všetkými jej vizuálmi. Keďže zaznamenaný stav pochádza z inej strany zostavy s rôznymi vizuálmi, všetky neplatné vizuály sa z konfigurácie záložiek odstránia. Ak tiež skopírujete závislé vizuály a stranu, záložka si zachová konfiguráciu.

Scenár:Skopíroval som priečinok stránky z inej zostavy a vyskytla som chybu s textom: "Hodnoty vlastnosti pageBinding.name musia byť jedinečné."

Riešenie: Objekt pageBinding je potrebný na podporu podrobnej analýzy a popisov stránky. Keďže na ne môžu odkazovať iné strany, názov musí byť v zostave jedinečný. Na novo skopírovanej stránke priraďte jedinečnú hodnotu, ktorá vyrieši chybu. Po júni 2024 sa s tým už problém nevyrieši, pretože názov pageBinding je predvolene identifikátor GUID.

Konverzia existujúcej zostavy na PBIR

PBIR je všeobecne dostupná a je predvoleným formátom zostavy. Zostavy, ktoré používajú PBIR-Legacy, môžete stále otvoriť v aplikácii Power BI Desktop a v Power BI service. Pri úprave a ukladaní zostavy PBIR-Legacy Power BI ticho a automaticky ju konvertuje na PBIR.

Pred konverziou Power BI vytvorí zálohu zostavy:

  • Power BI Desktop uchováva zálohu na 30 dní v jednom z nasledujúcich umiestnení:
    • Verzia z lokality Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Verzia spustiteľného inštalátora: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • V Power BI service sa uchováva PBIR-Legacy 28 dní. Ak ho chcete obnoviť, otvorte v pracovnom priestore nastavenia zostavy a vyberte možnosť Obnoviť ako PBIR-Legacy. Toto zálohovanie sa vytvorí iba pre zostavy skonvertované priamo v Power BI service.

Obnovenie PBIR-Legacy zálohovania nebráni ďalšej konverzii. Ak chcete zachovať zostavu vo formáte PBIR-Legacy, neupravujte ju v Power BI service ani nepoužívajte vydanie aplikácie Power BI Desktop vydané pred septembrom 2026.

Dôležité informácie a obmedzenia týkajúce sa PBIR

Pamätajte na tieto dôležité informácie a obmedzenia:

  • Automatické filtre vizuálu sa zachovajú do súboru PBIR visual.json iba potom, ako bola tabla filtrov rozbalená aspoň raz pri úprave zostavy.
  • Ak Power BI pri úprave a ukladaní neskonvertuje PBIR-Legacy zostavu na PBIR, konverzia sa stretla s problémom s produktom. Vytvorte žiadosť o podporu na nahlásenie problému.

Obmedzenia veľkosti PBIR vynútené službou:

  • max. 1 000 strán na zostavu.
  • 1000 maximálnych vizuálov na stránku.
  • max. 1 000 súborov balíkov prostriedkov na zostavu.
  • Maximálna veľkosť pre všetky súbory balíkov prostriedkov: 300 mb.
  • Maximálna veľkosť 300 mb pre všetky súbory zostáv.

Important

Ak dosiahnete vyššie uvedené limity, mali by ste zvážiť optimalizáciu prehľadu. Pozrite si dokument Optimalizácia služby Power BI.

Fabric integrácie Git a rozhrania Fabric REST API exportujú definície zostáv pomocou PBIR.

Súvisiaci obsah

  • Naposledy aktualizované: