folder z raportami projektu Power BI Desktop

Artykuł opisuje pliki i podfoldery w katalogu Report projektu Microsoft Power BI Desktop. Pliki i podfoldery tutaj reprezentują raport Power BI. W zależności od projektu, folder raportu może zawierać:

1 - Ten plik jest wymagany.
2 — Ten plik jest wymagany do formatowania PBIR-Legacy.
3 — Ten plik jest wymagany dla formatu PBIR.

Nie każdy folder raportu projektu zawiera wszystkie pliki i podfoldery opisane tutaj.

Pliki raportu

.pbi\localSettings.jsna

Zawiera ustawienia raportu, które dotyczą tylko bieżącego użytkownika i lokalnego komputera. Powinien zostać uwzględniony w repozytorium gitIgnore lub w innych wykluczeniach kontroli źródła. Domyślnie Git ignoruje ten plik.

Aby uzyskać więcej informacji, zobacz dokument schematu localSettings.json.

CustomVisuals\

Podkatalog zawierający metadane dla wizualizacji niestandardowych w raporcie. Power BI obsługuje trzy rodzaje wizualizacji niestandardowych.

  • Organizacyjne wizualizacje sklepu - Organizacje mogą zatwierdzać i wdrażać niestandardowe wizualizacje do Power BI dla swojej organizacji. Aby dowiedzieć się więcej, zobacz Magazyn organizacji.
  • Wizualizacje Power BI w AppSource - znane również jako "publiczne wizualizacje niestandardowe". Te wizualizacje są dostępne w Microsoft AppSource. Twórcy raportów mogą instalować te wizualizacje bezpośrednio z Power BI Desktop.
  • Pliki wizualizacji niestandardowych - Znane również jako "Prywatne wizualizacje niestandardowe". Pliki można załadować do raportu, wgrywając pakiet pbiviz.

Do folderu CustomVisuals ładowane są tylko prywatne wizualizacje niestandardowe. Wizualizacje z AppSource oraz wizualizacje organizacji są automatycznie ładowane przez Power BI Desktop.

RegisteredResources\

Podfolder zawierający pliki zasobów specyficzne dla raportu i załadowany przez użytkownika, taki jak motywy niestandardowe, obrazy i wizualizacje niestandardowe (pliki pbiviz).

Deweloperzy są odpowiedzialni za pliki w tym miejscu, a zmiany są zatwierdzane. Na przykład można zmienić plik i po ponownym uruchomieniu programu Power BI Desktop nowy plik zostanie załadowany do raportu. Ten folder może odblokować kilka przydatnych scenariuszy, takich jak:

  • Tworzenie motywów niestandardowych poza programem Power BI Desktop przy użyciu schematu publicznego.
  • Stosowanie zmian wsadowych poprzez edytowanie pliku zasobów w wielu raportach. Na przykład można przełączyć firmowy motyw niestandardowy, zmieniać między jasnym a ciemnym motywem oraz zmienić obrazy logotypu.

Każdy plik zasobów musi mieć odpowiedni wpis w pliku report.json. Edycje plików RegisteredResources są obsługiwane tylko w przypadku już załadowanych zasobów, które powodują zarejestrowanie zasobu w programie Power BI Desktop w report.json.

semanticModelDiagramLayout.json

Zawiera diagramy modelu danych opisujące strukturę modelu semantycznego skojarzonego z raportem. Ten plik nie obsługuje edycji zewnętrznej.

definition.pbir

Zawiera ogólną definicję raportu i ustawień podstawowych. Ten plik zawiera również odwołanie do modelu semantycznego używanego przez raport. Program Power BI Desktop może bezpośrednio otworzyć plik PBIR, tak samo jak w przypadku otwarcia raportu z pliku PBIP. Otwarcie pliku PBIR powoduje również otwarcie modelu semantycznego obok elementu , jeśli istnieje względne odwołanie przy użyciu polecenia byPath.

Przykład definicja.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"
    }    
  }
}

Definicja zawiera datasetReference właściwość, która odwołuje się do modelu semantycznego używanego w raporcie. Odwołanie może być jednym z następujących:

byPath - Określa ścieżkę względną do docelowego folderu semantycznego modelu. Ścieżki bezwzględne nie są obsługiwane. Ukośnik (/) jest używany jako separator katalogu. Gdy jest używane, Power BI Desktop również otwiera model semantyczny w pełnym trybie edycji.

byConnection — Określa połączenie z modelem semantycznym w obszarze roboczym Fabric za pomocą ciągu połączenia. Gdy używana jest referencja byConnection, Power BI Desktop nie otwiera modelu semantycznego w trybie edycji.

byConnection Przy użyciu odwołania należy określić następujące właściwości:

Nieruchomość Opis
Parametry połączenia Ciąg połączenia odwołujący się do modelu semantycznego w obszarze roboczym Fabric.

Przykład użycia 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]"
    }
  }
}

Podczas wdrażania raportu za pośrednictwem interfejsu Fabric REST API wystarczy określić tylko właściwość semanticmodelid. Przykład:

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

Ważne

Podczas wdrażania raportu za pomocą Fabric REST API należy użyć byConnection odwołań. Nie należy tego mylić z trybem przechowywania modelu semantycznego, takiego jak DirectQuery. Element datasetReference w raporcie określa tylko, z którym semantycznym modelem łączy się raport, nie definiuje sposobu przechowywania lub uzyskiwania dostępu do danych przez model.

Wiele plików *.pbir

Gdy model semantyczny i raport współdzielą ten sam obszar roboczy, Fabric Git Integration zawsze eksportuje definicje z odwołaniem byPath do modelu semantycznego. Jeśli chcesz wymusić otwarcie raportu w trybie połączenia na żywo (na przykład w celu pracy z miarami na poziomie raportu), możesz mieć wiele plików *.pbir, takich jak jeden z połączeniem byPath, a drugi z połączeniem byConnection. Integracja z Git w Fabric przetwarza tylko plik definition.pbir i ignoruje wszystkie inne pliki *.pbir. Jednak te pliki mogą współistnieć w tym samym repozytorium.

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

Plik definition.pbir określa również obsługiwane formaty definicji raportu za pomocą właściwości "version".

wersja Obsługiwane formaty
1.0 Definicja raportu musi być przechowywana jako PBIR-Legacy w pliku report.json.
4.0 lub nowsza Definicja raportu może być przechowywana jako PBIR-Legacy (plik report.json) lub PBIR (folder \definition).

Aby uzyskać więcej informacji, zobacz dokument schematu definition.pbir.

mobileState.json

Zawiera ustawienia wyglądu i zachowania raportu podczas renderowania na urządzeniu mobilnym. Ten plik nie obsługuje edycji zewnętrznej.

report.json

Ten plik zawiera definicję raportu w formacie Power BI Report Legacy (PBIR-Legacy) i nie obsługuje zewnętrznej edycji.

katalog definicji

Ten folder jest dostępny tylko wtedy, gdy projekt Power BI zostanie zapisany przy użyciu ulepszonego formatu raportu Power BI (PBIR). Zastępuje plik report.json.

.platforma

Plik platformy Fabric, który zawiera właściwości niezbędne do nawiązania i utrzymania połączenia między elementami Fabric a Git.

Aby dowiedzieć się więcej, zobacz Zintegrowane z Git automatycznie generowane pliki systemowe.

Format PBIR

Zapisywanie plików projektu Power BI (PBIP) przy użyciu ulepszonego formatu raportu Power BI (PBIR) znacznie poprawia śledzenie zmian i rozwiązywanie konfliktów scalania poprzez użycie poprawnie sformatowanych plików JSON.

Zrzut ekranu przyjaznych różnic PBIR.

Każda strona, wizualizacja, zakładka itd., jest zorganizowana w osobny, indywidualny plik w strukturze folderów. Ten format jest idealny do rozwiązywania konfliktów tworzenia kodu.

Zrzut ekranu przyjaznego folderu PBIR.

W przeciwieństwie do PBIR-Legacy (report.json), PBIR to publicznie udokumentowany format, który wspiera modyfikacje z aplikacji innych niż Power BI. Każdy plik ma publiczny schemat JSON, który nie tylko dokumentuje plik, ale także pozwala edytorom kodu, takim jak Visual Studio Code, wykonywać walidację składni podczas edytowania.

Niektóre z możliwych scenariuszy dostępnych obecnie z PBIR obejmują:

  • Kopiowanie stron/wizualizacji/zakładek między raportami.
  • Zapewnij spójność zestawu wizualizacji na wszystkich stronach, poprzez kopiowanie i wklejanie plików wizualnych.
  • Łatwe wyszukiwanie i zastępowanie w wielu plikach raportów.
  • Stosowanie edycji wsadowej we wszystkich wizualizacjach przy użyciu skryptu (na przykład ukrywanie filtrów na poziomie wizualizacji)

Zapisz jako projekt używając PBIR

Podczas zapisywania projektu przy użyciu narzędzia PBIR raport jest zapisywany w folderze o nazwie \definition w folderze raportu:

Zrzut ekranu folderu definicji wewnątrz folderu PBIP raportu.

Dowiedz się więcej o strukturze folderów PBIR.

Folder PBIR i pliki

Definicja raportu jest przechowywana w folderze definition\ o następującej strukturze:

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json
Plik/folder Wymagane Opis
zakładki Nie. Folder zawierający wszystkie pliki zakładek raportu.
{} [bookmarkName].bookmark.json Nie. Metadane zakładek, takie jak docelowe elementy wizualne i filtry.
Więcej informacji na schema.
\\ bookmarks.json Nie. Metadane zakładek, takie jak kolejność zakładek i grupy.
Więcej informacji na schema.
strony Tak Folder zawierający wszystkie strony raportu.
{} [pageName]\ Tak Jeden folder na stronę.
──── Wizualizacje\ Nie. Folder zawierający wszystkie wizualizacje strony.
────── [visualName]\ Nie. Jeden folder na wizualizację.
──────── mobile.json Nie. Wizualne metadane układu mobilnego, takie jak położenie i formatowanie dla urządzeń przenośnych.
Więcej informacji na schema.
─────── visual.json Tak Wizualne metadane, takie jak pozycja i formatowanie, zapytanie.
Więcej informacji na schema.
\\\\\ page.json Tak Metadane strony, takie jak filtry na poziomie strony i formatowanie.
Więcej informacji na schema.
\\ pages.json Nie. Metadane stron, takie jak kolejność stron i aktywna strona.
Więcej informacji na schema.
version.json Tak Wersja pliku PBIR, wraz z innymi czynnikami, określa pliki wymagane do załadowania.
Więcej informacji na schema
reportExtensions.json Nie. Rozszerzenia raportów, takie jak miary na poziomie raportu.
Więcej informacji na schema
report.json Tak Metadane raportu, takie jak filtry poziomu raportu i formatowanie.
Więcej informacji na schema

Ważne

Niektóre pliki metadanych raportu, takie jak visual.json lub bookmarks.json, mogą być zapisywane przy użyciu wartości danych z modelu semantycznego. Jeśli na przykład zastosujesz filtr do wizualizacji dla pola "Company" = "Contoso", wartość "Contoso" będzie zachowywana jako część metadanych. Dotyczy to również innych konfiguracji, takich jak wybory fragmentatora, szerokość niestandardowych kolumn macierzy i formatowanie dla określonej serii.

Konwencja nazewnictwa PBIR

Wszystkie nazwy wewnątrz nawiasów kwadratowych ([]) w poprzedniej tabeli stosują domyślny schemat nazewnictwa, ale mogą być zmienione na bardziej przyjazne dla użytkownika nazwy. Domyślnie strony, wizualizacje i zakładki używają nazwy obiektu raportu jako swojej nazwy pliku lub folderu. Nazwy tych obiektów początkowo są 20-znakowym unikalnym identyfikatorem, takim jak '90c2e07d8e84e7d5c026'.

Zrzut ekranu właściwości nazwy PBIR.

Zmiana nazwy właściwości 'name' w każdym pliku JSON jest obsługiwana, ale może spowodować problemy z zewnętrznymi odwołaniami zarówno wewnątrz, jak i na zewnątrz raportu. Nazwa obiektu i/lub nazwa pliku/folderu musi składać się z co najmniej jednego znaku słowa (liter, cyfr, podkreśleń) lub łączników.

Po zmianie nazwy dowolnych plików lub folderów PBIR musisz ponownie uruchomić Power BI Desktop. Po ponownym uruchomieniu Power BI Desktop zachowa oryginalne nazwy plików lub folderów podczas zapisywania.

Kopiowanie nazwy obiektu raportu

Każdy obiekt w raporcie jest zapisywany w osobnym folderze lub pliku, ale nazwa folderu nie zawsze jest oczywista. Aby to ułatwić, możesz skopiować nazwę dowolnego obiektu raportu (w tym strony, wizualizacje, zakładki i filtry) bezpośrednio z usługi Power BI do schowka.

Zrzut ekranu przedstawiający raport ze strzałką wskazującą jedną z wizualizacji na nazwę odpowiadającego mu pliku.

  1. Przejdź do pozycji Opcje > Pliku i Ustawienia > Ustawienia raportu > Obiekty raportu i włącz opcję Kopiuj nazwy obiektów po kliknięciu prawym przyciskiem myszy na obiektach raportu. Należy to zrobić tylko raz.

    Zrzut ekranu przedstawiający ustawienia obiektów raportu.

  2. Kliknij prawym przyciskiem myszy dowolny obiekt raportu i wybierz polecenie Kopiuj nazwę obiektu.

    Zrzut ekranu przedstawiający raport pulpitu z wybraną nazwą obiektu kopiowania.

Nazwa obiektu skopiowana do schowka umożliwia łatwe wprowadzenie jej na pasku wyszukiwania Eksploratora Windows lub programu Visual Studio Code w celu zlokalizowania lub zidentyfikowania nazwy obiektu w folderze PBIR.

Zrzut ekranu przedstawiający pasek wyszukiwania z nazwą obiektu.

Schematy JSON usługi PBIR

Każdy plik JSON usługi PBIR zawiera deklarację schematu JSON w górnej części dokumentu. Ten adres URL schematu jest publicznie dostępny i może służyć do uzyskania dodatkowych informacji o dostępnych właściwościach i obiektach dla każdego pliku. Ponadto zapewnia wbudowaną funkcję IntelliSense i walidację podczas edytowania za pomocą edytorów kodu, takich jak Visual Studio Code.

Zrzut ekranu przedstawiający podpowiedź schematu JSON PBIR.

URL schematu również definiuje wersję dokumentu, która może się zmieniać wraz z rozwojem definicji raportu.

Wszystkie schematy JSON są tutaj publikowane.

PBIR adnotacje

Możesz dołączyć adnotacje jako pary nazwa-wartość w definicji raportu dla każdego visual, page i report. Program Power BI Desktop ignoruje te adnotacje, ale mogą być przydatne w przypadku aplikacji zewnętrznych, takich jak skrypty.

Można na przykład określić domyślną stronę dla raportu w pliku report.json, który następnie może być wykorzystywany przez skrypt wdrożenia.

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

Zmiany zewnętrzne w plikach PBIR

Obsługiwane pliki JSON usługi PBIR można edytować w edytorze kodu, na przykład Visual Studio Code lub innym narzędziem zewnętrznym, podczas gdy projekt pozostaje otwarty w programie Power BI Desktop. Podczas zapisywania plików program Power BI Desktop wykrywa zmiany i wyświetla baner Zastosuj zmiany zewnętrzne. Wybierz pozycję Zastosuj zmiany zewnętrzne , aby ponownie załadować definicję raportu bez zamykania i ponownego otwierania projektu.

Przed zewnętrzną edycją plików PBIR zapisz wszelkie zmiany w programie Power BI Desktop. Jeśli Power BI Desktop ma niezapisane zmiany podczas stosowania zmian zewnętrznych, ostrzega, że niezapisane zmiany zostaną zastąpione. Aby uzyskać pełny przepływ pracy i ograniczenia, zobacz Edytowanie plików PBIP poza programem Power BI Desktop.

Pliki PBIR muszą być zgodne ze schematami JSON. Program VS Code identyfikuje problemy, takie jak nieobsługiwana nazwa właściwości lub nieprawidłowy typ właściwości:

Zrzut ekranu z walidacji schematu JSON PBIR.

Zmiany zewnętrzne zawartości usługi PBIR mogą powodować błędy podczas stosowania zmian lub otwierania plików w programie Power BI Desktop. Te błędy mogą być dwoma typami:

Błędy blokujące uniemożliwiają Power BI Desktop ładowanie zmian raportu. Te błędy identyfikują problem i plik, który należy rozwiązać przed ponownym zastosowaniem zmian:

Zrzut ekranu błędu blokowania PBIR.

Błędy, takie jak nieprawidłowy schemat lub brakujące wymagane właściwości, blokują błędy. Aby zidentyfikować te błędy, otwórz plik w programie VS Code i sprawdź komunikaty sprawdzania poprawności schematu.

Błędy nieblokacyjne nie uniemożliwiają programowi Power BI Desktop otwierania raportu i są automatycznie rozwiązywane.

Zrzut ekranu przedstawiający komunikat o błędzie braku odblokowania usługi PBIR.

Nieprawidłowa activePageName konfiguracja to przykład błędu nieblokowania, który Power BI Desktop naprawia automatycznie. Ostrzeżenie daje możliwość przejrzenia poprawki przed zapisaniem raportu i zastąpieniem definicji zewnętrznej.

Typowe błędy usługi PBIR

Scenariusz:Po zmianie nazw folderów wizualizacji lub stron, moje wizualizacje lub strony nie pojawiają się już przy otwieraniu raportu.

Rozwiązanie: Sprawdź, czy nazwa jest zgodna z konwencją nazewnictwa. Jeśli nie, Power BI Desktop ignoruje plik lub folder i traktuje go jako plik prywatny użytkownika.

Scenariusz:Nowe obiekty raportu są nazwane inaczej niż pozostałe. Na przykład, większość folderów stron jest nazwana 'ReportSection0e71dafbc949c0853608', podczas gdy kilka z nich jest nazywanych '1b3c2ab12b603618070b'.

Rozwiązanie: PBIR przyjęło nową konwencję nazewnictwa dla każdego obiektu, ale dotyczy ona tylko nowych obiektów. Kiedy zapisujesz istniejący raport jako PBIP, bieżące nazwy muszą zostać zachowane, aby zapobiec łamaniu odwołań. Jeśli chcesz uzyskać spójność, dozwolone jest użycie skryptu do zmiany nazwy wielu plików.

Scenariusz:Skopiowano plik zakładki i po zapisaniu większość konfiguracji zakładki została usunięta.

Rozwiązanie: To zachowanie jest zamierzone, zakładki raportów przechwytują stan strony raportu wraz ze wszystkimi jej wizualizacjami. Ponieważ przechwycony stan pochodzi z innej strony raportu z różnymi wizualizacjami, wszelkie nieprawidłowe wizualizacje zostają usunięte z konfiguracji zakładki. Jeśli skopiujesz również zależne wizualizacje i stronę, zakładka zachowa swoją konfigurację.

Scenariusz:Skopiowano folder strony z innego raportu i wystąpił błąd z informacją: "Wartości właściwości "pageBinding.name" muszą być unikatowe.

Rozwiązanie: Obiekt pageBinding jest niezbędny do obsługi przechodzenia do szczegółów i wskazówek dotyczących strony. Ponieważ mogą być odwołania z innych stron, nazwa musi być unikalna w raporcie. Na nowo skopiowanej stronie przypisz unikalną wartość, aby rozwiązać błąd. Po czerwcu 2024 r. ta sytuacja nie jest już problemem, ponieważ nazwa pageBinding jest domyślnie identyfikatorem GUID.

Konwertowanie istniejącego raportu na usługę PBIR

Usługa PBIR jest ogólnie dostępna i jest domyślnym formatem raportu. Nadal można otwierać raporty, które używają PBIR-Legacy w programie Power BI Desktop i usługa Power BI. Podczas edytowania i zapisywania raportu PBIR-Legacy Power BI dyskretnie i automatycznie konwertuje go na usługę PBIR.

Przed konwersją Power BI tworzy kopię zapasową raportu:

  • Power BI Desktop przechowuje kopię zapasową przez 30 dni w jednej z następujących lokalizacji:
    • Wersja sklepu Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
    • Wersja instalatora wykonywalnego: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
  • Usługa Power BI przechowuje kopię zapasową PBIR-Legacy przez 28 dni. Aby go przywrócić, w obszarze roboczym otwórz Ustawienia raportu i wybierz Przywróć jako PBIR-Legacy. Ta kopia zapasowa jest tworzona tylko dla raportów przekonwertowanych bezpośrednio w usługa Power BI.

Przywracanie kopii zapasowej PBIR-Legacy nie uniemożliwia innej konwersji. Aby zachować raport w formacie PBIR-Legacy, nie edytuj go w usługa Power BI lub użyj wydania programu Power BI Desktop wydanego przed wrześniem 2026 r.

Zagadnienia i ograniczenia dotyczące usługi PBIR

Należy pamiętać o następujących zagadnieniach i ograniczeniach:

  • Automatyczne filtry wizualne są utrwalane w pliku PBIR visual.json dopiero po rozwinięciu panelu filtrów co najmniej raz podczas edytowania raportu.
  • Jeśli Power BI nie konwertuje raportu PBIR-Legacy na usługę PBIR podczas edytowania i zapisywania go, konwersja napotkała problem z produktem. Utwórz wniosek o pomoc techniczną, aby zgłosić problem.

Ograniczenia rozmiaru PBIR narzucane przez usługę:

  • 1,000 stron maksymalnie na raport.
  • 1000 maksymalnych wizualizacji na stronę.
  • Maksymalnie 1,000 plików pakietu zasobów na raport.
  • Maksymalny rozmiar 300 MB dla wszystkich plików pakietu zasobów.
  • Maksymalny rozmiar wszystkich plików raportu: 300 MB.

Ważne

Jeśli osiągniesz powyższe limity, rozważ optymalizację raportu. Zobacz dokument Dotyczący optymalizacji usługi Power BI.

Integracja usługi Fabric z usługą Git oraz interfejsy API REST usługi Fabric eksportują definicje raportów w formacie PBIR.

Powiązana treść

  • Last updated on