Folder raportu projektu programu Power BI Desktop

Ważne

Projekty programu Power BI Desktop są obecnie dostępne w wersji zapoznawczej.

W tym artykule opisano pliki i podfoldery w folderze Raport projektu programu Microsoft Power BI Desktop. Pliki i podfoldery w tym miejscu reprezentują raport usługi Power BI. W zależności od projektu folder raportu może zawierać następujące elementy:

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• ^{report.json 2}
• definition\ folder³
• .podest

1 — Ten plik jest wymagany.
2 — Ten plik jest wymagany podczas zapisywania w formacie PBIR-Legacy.
3 — Ten plik jest wymagany podczas zapisywania w formacie PBIR.

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

Pliki raportów

.pbi\localSettings.json

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

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

CustomVisuals\

Podfolder zawierający metadane wizualizacji niestandardowych w raporcie. Usługa Power BI obsługuje trzy rodzaje wizualizacji niestandardowych:

• Wizualizacje magazynu organizacyjnego — organizacje mogą zatwierdzać i wdrażać wizualizacje niestandardowe w usłudze Power BI dla swojej organizacji. Aby dowiedzieć się więcej, zobacz Magazyn organizacji.
• Wizualizacje usługi Power BI w usłudze AppSource — znane również jako "Publiczne wizualizacje niestandardowe". Te wizualizacje są dostępne w witrynie Microsoft AppSource. Deweloperzy raportów mogą instalować te wizualizacje bezpośrednio z programu Power BI Desktop.
• Pliki wizualizacji niestandardowych — nazywane również "prywatnymi wizualizacjami niestandardowymi". Pliki można załadować do raportu, przekazując pakiet pbiviz.

Tylko prywatne wizualizacje niestandardowe są ładowane do folderu CustomVisuals. Wizualizacje usługi AppSource i organizacji są ładowane automatycznie przez program 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ą obsługiwane. 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 przez zmianę pliku zasobu w wielu raportach. Na przykład można przełączyć motyw niestandardowy firmy, zmienić motyw między jasnymi i ciemnymi motywami i zmienić obrazy logo.

Każdy plik zasobu musi mieć odpowiedni wpis w pliku report.json, który podczas podglądu nie obsługuje edycji. 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. W wersji zapoznawczej 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 pbir otwiera również semantyczny model obok, jeśli istnieje względne odwołanie przy użyciu polecenia byPath.

Przykład definition.pbir:

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

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

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 folderu. W przypadku użycia program Power BI Desktop otwiera również semantyczny model w trybie pełnej edycji.

byConnection- Określa zdalny model semantyczny w usługa Power BI przy użyciu parametry połączenia. W przypadku byConnection użycia odwołania program 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:

Właściwości	Opis
Parametry połączenia	Parametry połączenia odwołujące się do zdalnego modelu semantycznego.
pbiModelDatabaseName	Identyfikator modelu semantycznego zdalnego.
connectionType	Typ połączenia. W przypadku zdalnego modelu semantycznego usługi ta wartość powinna mieć wartość pbiServiceXmlaStyleLive.
pbiModelVirtualServerName	Właściwość wewnętrzna, która powinna mieć wartość . sobe_wowvirtualserver

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

Gdy semantyczny model i raport współużytkuje ten sam obszar roboczy, integracja z usługą byPath Git w sieci szkieletowej zawsze używa odwołania do modelu semantycznego.

Ten plik 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 nowsze	Definicję raportu można przechowywać jako PBIR-Legacy (plik report.json) lub PBIR (\definition folder).

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

mobileState.json

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

report.json

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

definition\ folder

Ten folder jest dostępny tylko wtedy, gdy projekt usługi Power BI jest zapisywany przy użyciu rozszerzonego formatu raportu (PBIR) usługi Power BI. Zastępuje on plik report.json .

.podest

Plik platformy sieci szkieletowej, który zawiera właściwości niezbędne do ustanawiania i obsługi połączenia między elementami sieci szkieletowej i usługą Git.

Aby dowiedzieć się więcej, zobacz Integracja usługi Git automatycznie wygenerowanych plików systemowych.

Format pbIR

Ważne

Weź pod uwagę wszystkie ograniczenia usługi PBIR w fazie zapoznawczej.

Zapisanie plików projektu usługi Power BI (PBIP) przy użyciu rozszerzonego formatu raportu usługi Power BI (PBIR) znacznie poprawia śledzenie zmian i rozwiązywanie konfliktów scalania przy użyciu poprawnie sformatowanych plików JSON.

Każda strona, wizualizacja, zakładka itp. jest zorganizowana w oddzielny, pojedynczy plik w strukturze folderów. Ten format jest idealny do rozwiązywania konfliktów współtworzenia.

W przeciwieństwie do wersji PBIR-Legacy (report.json), usługa PBIR jest publicznie udokumentowanym formatem obsługującym modyfikacje aplikacji innych niż Power BI. Każdy plik ma publiczny schemat JSON, który nie tylko dokumentuje plik, ale także umożliwia edytorom kodu, takich jak Visual Studio Code, przeprowadzanie walidacji składni podczas edytowania.

Oto niektóre z możliwych scenariuszy dostępnych teraz w usłudze PBIR:

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

Włączanie funkcji podglądu formatu PBIR

Zapisywanie jako projekt usługi Power BI przy użyciu usługi PBIR jest obecnie dostępne w wersji zapoznawczej. Przed użyciem włącz ją w funkcjach programu Power BI Desktop w wersji zapoznawczej:

Przejdź do pozycji Opcje plików > i ustawienia > Opcje > w wersji zapoznawczej i zaznacz pole wyboru obok pozycji Przechowywanie raportów przy użyciu rozszerzonego formatu metadanych (PBIR).

Zapisywanie jako projektu przy użyciu usługi PBIR

Po włączeniu funkcji PBIR Preview podczas zapisywania projektu raport jest zapisywany w folderze o nazwie \definition wewnątrz folderu raportu:

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

Konwertowanie istniejącej usługi PBIP na usługę PBIR

Jeśli masz już usługę PBIP w formacie PBIR-Legacy, możesz przekonwertować go na usługę PBIR w następujący sposób:

1. Otwórz usługę PBIP w programie Power BI Desktop.

2. Upewnij się, że funkcja w wersji zapoznawczej jest włączona.

3. Zapisz projekt. Zostanie wyświetlony monit z prośbą o uaktualnienie do usługi PBIR.

4. Wybierz pozycję Uaktualnij.

   

   Ważne

   Po uaktualnieniu do usługi PBIR nie można powrócić do wersji PBIR-Legacy. Jeśli uważasz, że warto wrócić do wersji PBIR-Legacy, najpierw zapisz kopię plików PBIP.

Istniejący plik PBIR-Legacy (report.json) jest zastępowany folderem \definition zawierającym reprezentację pbIR raportu.

Jeśli wybierzesz opcję Zachowaj bieżący format, program Desktop nie monituj ponownie o uaktualnienie.

Publikowanie raportu PBIR w usłudze

W fazie wersji zapoznawczej jedynym sposobem opublikowania raportu w formacie PBIR jest integracja z usługą Git Fabric. Obejmuje to połączenie obszaru roboczego z repozytorium Git i wypchnięcie do niego raportu PBIR, który następnie można zsynchronizować z obszarem roboczym usługi na późniejszym etapie.

Jeśli chcesz przekonwertować istniejący raport na usługę PBIR, wykonaj następujące kroki:

1. Połącz obszar roboczy z usługą Git.
2. Sklonuj repozytorium Git do lokalnego systemu plików.
3. Otwórz raport w programie Power BI Desktop, otwierając definition.pbir plik.
4. Zapisz raport i wybierz uaktualnienie do usługi PBIR.
5. Zatwierdź i zsynchronizuj zmiany w usłudze Git.
6. Zaktualizuj obszar roboczy przy użyciu najnowszych zmian z usługi Git.

Folder i pliki USŁUGI PBIR

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	Wymagania	opis
Zakładki\	Nie.	Folder zawierający wszystkie pliki zakładek raportu.
{} [bookmarkName].bookmark.json	Nie.	Metadane zakładek, takie jak wizualizacje docelowe i filtry. Więcej informacji znajduje się w schemacie.
\\ bookmarks.json	Nie.	Metadane zakładek, takie jak kolejność zakładek i grupy. Więcej informacji znajduje się w schemacie.
Stron\	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 znajduje się w schemacie.
──────── visual.json	Tak	Metadane wizualizacji, takie jak położenie i formatowanie, zapytanie. Więcej informacji znajduje się w schemacie.
\\\\\ page.json	Tak	Metadane strony, takie jak filtry na poziomie strony i formatowanie. Więcej informacji znajduje się w schemacie.
\\ pages.json	Nie.	Metadane stron, takie jak kolejność stron i aktywna strona. Więcej informacji znajduje się w schemacie.
version.json	Tak	Między innymi wersja pliku PBIR określa wymagane pliki do załadowania. Więcej informacji na temat schematu
reportExtensions.json	Nie.	Rozszerzenia raportów, takie jak miary na poziomie raportu. Więcej informacji na temat schematu
report.json	Tak	Metadane raportu, takie jak filtry na poziomie raportu i formatowanie. Więcej informacji na temat schematu

Konwencja nazewnictwa usługi PBIR

Wszystkie nazwy wewnątrz nawiasów kwadratowych ([]) w poprzedniej tabeli są zgodne z domyślną konwencją nazewnictwa, ale można zmienić jej nazwę na bardziej przyjazne dla użytkownika nazwy. Domyślnie strony, wizualizacje i zakładki używają nazwy obiektu raportu jako nazwy pliku lub folderu. Te nazwy obiektów są początkowo unikatowym identyfikatorem 20 znaków, takim jak "90c2e07d8e84e7d5c026".

Zmiana nazwy właściwości "name" w każdym pliku JSON jest obsługiwana, ale może spowodować przerwanie odwołań zewnętrznych zarówno wewnątrz, jak i poza raportem. 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 wszystkich plików lub folderów PBIR należy ponownie uruchomić program Power BI Desktop. Po ponownym uruchomieniu program Power BI Desktop zachowa oryginalne nazwy plików lub folderów podczas zapisywania.

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.

Adres URL schematu definiuje również wersję dokumentu, która powinna ulec zmianie w miarę rozwoju definicji raportu.

Wszystkie schematy JSON są tutaj publikowane.

Adnotacje usługi PBIR

Adnotacje można uwzględnić jako pary name-value w definicji raportu dla każdego visualelementu i page report. Program Power BI Desktop zignoruje te adnotacje, ale może być cenny dla aplikacji zewnętrznych, takich jak skrypty.

Można na przykład określić domyślną stronę raportu w report.json pliku, który następnie może być używany 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

Pliki JSON pbIR można edytować przy użyciu edytora kodu, takiego jak Program Visual Studio Code lub narzędzie zewnętrzne, o ile plik jest przestrzegany schematu JSON. Użycie nieprawidłowej nazwy lub typu właściwości można łatwo wykryć bezpośrednio w programie Visual Studio Code:

Zmiany zewnętrzne zawartości pbIR mogą powodować błędy podczas ponownego otwierania plików w programie Power BI Desktop. Te błędy mogą być dwoma typami:

Błędy blokujące uniemożliwiają programowi Power BI Desktop otwieranie raportu. Te błędy pomagają zidentyfikować problem i plik, który należy naprawić przed ponownym otwarciem:

Błędy, takie jak nieprawidłowy schemat lub brakujące wymagane właściwości, są uznawane za błędy blokujące. Te błędy można łatwo zidentyfikować, otwierając plik w programie Visual Studio Code i sprawdzając błędy schematu.

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

Błędy, takie jak nieprawidłowa konfiguracja activePageName , to przykłady błędów nieblokujących, które są automatycznie naprawiane. Ostrzeżenie jest niezbędne, aby umożliwić uniknięcie zapisywania raportu z autofiksem, co uniemożliwia potencjalną utratę pracy.

Typowe błędy usługi PBIR

Scenariusz: po zmianie nazwy nazw wizualizacji lub folderów stron moja wizualizacja lub strona nie będzie już wyświetlana podczas otwierania raportu.

Rozwiązanie: sprawdź, czy nazwa jest zgodna z konwencją nazewnictwa. Jeśli tak nie jest, program Power BI Desktop ignoruje plik lub folder i traktuje go jako pliki użytkowników prywatnych.

Scenariusz: Nowe obiekty raportów różnią się od innych. Na przykład większość folderów stron nosi nazwę "ReportSection0e71dafbc949c0853608", podczas gdy kilka z nich nosi nazwę "1b3c2ab12b603618070b".

Rozwiązanie: usługa PBIR przyjęła nową konwencję nazewnictwa dla każdego obiektu, ale dotyczy tylko nowych obiektów. Po zapisaniu istniejącego raportu jako pbIP bieżące nazwy muszą być zachowywane, aby zapobiec wystąpieniu odwołań powodujących niezgodność. Jeśli chcesz uzyskać spójność, skrypt dozwolony jest zmianą nazwy partii.

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, wszystkie nieprawidłowe wizualizacje są usuwane 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 przeglądania szczegółowego i etykietek narzędzi strony. Ponieważ mogą się odwoływać do nich inne strony, nazwa musi być unikatowa w raporcie. Na nowo skopiowanej stronie przypisz unikatową wartość, aby rozwiązać ten problem. Po czerwcu 2024 r. ta sytuacja nie jest już problemem, ponieważ nazwa pageBinding jest domyślnie identyfikatorem GUID.

Zagadnienia i ograniczenia dotyczące usługi PBIR

Usługa PBIR jest obecnie dostępna w wersji zapoznawczej. Należy pamiętać o następujących kwestiach:

• Ograniczenia usługi
  • Widoki mobilne nie są wyświetlane w aplikacjach usługi Power BI.
  • Nie można wdrożyć przy użyciu potoków wdrażania.
  • Nie można zapisać jako kopii.
• Duże raporty z ponad 500 plikami napotykają problemy z wydajnością tworzenia (wyświetlanie raportów nie ma wpływu), w tym:
  • Zapisywanie w programie Power BI Desktop
  • Synchronizacja w usłudze Git Integration
• Po przekonwertowaniu raportu z usługi PBIR-Legacy na usługę PBIR nie można wycofać go.
• Konwertowanie pliku PBIP na plik PBIX przy użyciu funkcji "Zapisz jako" osadza raport PBIR w pliku PBIX, przenosząc wszystkie ograniczenia pbIR do pliku PBIX.

Ograniczenia rozmiaru usługi PBIR wymuszane przez usługę:

• 1000 maksymalnych stron na raport.
• 300 maksymalnych wizualizacji na stronę.
• Maksymalny rozmiar 5 mb dla każdego pliku zakładki.
• Maksymalna wartość 1 MB dla każdego pliku.
• 1000 maksymalnych plików pakietów zasobów na raport.
• Maksymalny rozmiar 300 mb dla wszystkich plików pakietu zasobów.
• Maksymalny rozmiar wszystkich plików raportu: 20 MB.

W publicznej wersji zapoznawczej interfejsy API REST integracji i sieci szkieletowej usługi Git nadal używają wersji PBIR-Legacy (report.json) podczas eksportowania definicji raportu. Jeśli jednak raport jest importowany do sieci szkieletowej przy użyciu formatu PBIR, obie funkcje zaczynają eksportować definicję raportu przy użyciu formatu PBIR.

Powiązana zawartość

• Folder semantycznego modelu projektu programu Power BI Desktop
• Projekty programu Power BI Desktop