folder laporan proyek Power BI Desktop

Artikel ini menjelaskan file dan subfolder dalam folder Report dari proyek Microsoft Power BI Desktop. File dan subfolder di sini mewakili laporan Power BI. Tergantung pada proyek Anda, folder laporan dapat mencakup:

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

1 - File ini diperlukan.
2 - File ini diperlukan untuk format PBIR-Legacy.
3 - File ini diperlukan untuk format PBIR.

Tidak setiap folder laporan proyek mencakup semua berkas dan subfolder yang dijelaskan di sini.

File laporan

.pbi\localSettings.jsaktif

Berisi pengaturan laporan yang hanya berlaku untuk pengguna dan komputer lokal saat ini. Ini harus disertakan dalam gitIgnore atau pengecualian kontrol sumber lainnya. Secara default, Git mengabaikan file ini.

Untuk informasi lebih lanjut, lihat dokumen skema localSettings.json.

CustomVisuals\

Sebuah subfolder yang berisi metadata untuk visual khusus dalam laporan. Power BI mendukung tiga jenis visual kustom.

• Visual toko organisasi - Organisasi dapat menyetujui dan menerapkan visual kustom ke Power BI untuk organisasi mereka. Untuk mempelajari lebih lanjut, lihat Toko Organisasi.
• Visual Power BI AppSource - Juga dikenal sebagai "Visual kustom publik". Visual ini tersedia di Microsoft AppSource. Pengembang laporan dapat menginstal visual ini langsung dari Power BI Desktop.
• Berkas visual kustom - Juga dikenal sebagai "Visual kustom pribadi". File dapat dimuat ke dalam laporan dengan mengunggah paket pbiviz.

Hanya visual kustom privat yang dimuat ke dalam folder CustomVisuals. AppSource dan visual Organisasi dimuat secara otomatis oleh Power BI Desktop.

RegisteredResources\

Subfolder yang mencakup file sumber daya khusus untuk laporan dan dimuat oleh pengguna, seperti tema kustom, gambar, dan visual kustom (file pbiviz).

Pengembang bertanggung jawab atas file di sini dan perubahan didukung. Sebagai contoh, Anda dapat mengubah sebuah file dan setelah Power BI Desktop di-restart, file baru akan dimuat ke dalam laporan. Folder ini dapat membuka beberapa skenario yang berguna, seperti:

• Membuat tema khusus di luar Power BI Desktop dengan menggunakan skema publik.
• Menerapkan perubahan batch dengan mengubah file sumber pada beberapa laporan. Untuk contoh, Anda dapat mengganti tema kustom perusahaan, beralih antara tema terang dan gelap, dan mengubah gambar logo.

Setiap file sumber daya harus memiliki entri yang sesuai dalam file report.json. Pengeditan file RegisteredResources hanya didukung untuk sumber daya yang sudah dimuat yang menyebabkan Power BI Desktop mendaftarkan sumber daya tersebut dalam report.json.

semanticModelDiagramLayout.json

Memuat diagram model data yang menggambarkan struktur model semantik yang terkait dengan laporan. File ini tidak mendukung pengeditan eksternal.

definition.pbir

Berisi definisi keseluruhan dari sebuah laporan dan pengaturan inti. File ini juga menyimpan referensi terhadap model semantik yang digunakan oleh laporan. Power BI Desktop dapat membuka file PBIR secara langsung, sama seperti jika laporan dibuka dari file PBIP. Membuka file PBIR juga membuka model semantik bersama jika ada referensi relatif menggunakan byPath.

Contoh definisi.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"
    }    
  }
}

Definisi mencakup properti datasetReference, yang merujuk pada model semantik yang digunakan dalam laporan. Referensi dapat berupa:

byPath - Menentukan jalur relatif ke folder model semantik target. Jalur absolut tidak didukung. Tanda garis miring (/) digunakan sebagai pemisah folder. Saat digunakan, Power BI Desktop juga membuka model semantik dalam mode edit penuh.

byConnection - Menentukan koneksi ke model semantik di ruang kerja Fabric dengan menggunakan string koneksi. byConnection Saat referensi digunakan, Power BI Desktop tidak membuka model semantik dalam mode edit.

Versi 2

Menggunakan referensi byConnection, properti berikut harus ditentukan:

Properti	Deskripsi
koneksiString	String koneksi yang mengacu pada model semantik di ruang kerja Fabric.

Contoh menggunakan 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]"
    }
  }
}

Saat menyebarkan laporan melalui Fabric REST API, Anda hanya perlu menentukan semanticmodelid properti . Contohnya:

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

Versi 1

Menggunakan referensi byConnection, properti berikut harus ditentukan:

Properti	Deskripsi
koneksiString	String koneksi yang mengacu pada model semantik di ruang kerja Fabric.
pbiModelDatabaseName	ID model semantik jarak jauh.
jenisKoneksi	Jenis koneksi. Untuk layanan model semantik jarak jauh, nilai ini harus berupa pbiServiceXmlaStyleLive.
pbiModelVirtualServerName	Properti internal yang seharusnya memiliki nilai, sobe_wowvirtualserver.
pbiServiceModelId	Properti internal yang seharusnya memiliki nilai, null.
Nama	Properti internal yang seharusnya memiliki nilai, EntityDataSource.

Contoh menggunakan byConnection

{
    "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/1.0.0/schema.json",
    "version": "4.0",
    "datasetReference": {  
      "byConnection": {
        "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName];Initial Catalog=[SemanticModelName];Integrated Security=ClaimsToken",
        "pbiServiceModelId": null,
        "pbiModelVirtualServerName": "sobe_wowvirtualserver",
        "pbiModelDatabaseName": "[Semantic Model Id]",
        "connectionType": "pbiServiceXmlaStyleLive",
        "name": "EntityDataSource"
      }
  }
}

Penting

Saat menyebarkan laporan melalui Fabric REST API, Anda harus menggunakan byConnection referensi. Ini tidak boleh dikacaukan dengan mode penyimpanan model semantik seperti DirectQuery. datasetReference Dalam laporan hanya menentukan model semantik mana yang disambungkan laporan, laporan tidak menentukan bagaimana model tersebut menyimpan atau mengakses datanya.

Beberapa file *.pbir

Ketika model semantik dan laporan berbagi ruang kerja yang sama, Integrasi Fabric Git selalu mengekspor definisi dengan byPath referensi ke model semantik. Jika Anda ingin memaksa laporan terbuka dalam koneksi langsung (misalnya, untuk bekerja dengan langkah-langkah tingkat laporan), Anda dapat memiliki beberapa *.pbir file, seperti satu dengan koneksi byPath dan yang lain dengan koneksi byConnection. Fabric Git Integration hanya memproses file definition.pbir dan mengabaikan semua file *.pbir lainnya. Namun, file-file ini dapat berdampingan di repositori yang sama.

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

File definition.pbir juga menentukan format definisi laporan yang didukung melalui properti 'versi'.

Versi	Format yang didukung
1.0	Definisi laporan harus disimpan sebagai PBIR-Legacy di dalam file report.json.
4.0 atau lebih tinggi	Definisi laporan dapat disimpan sebagai PBIR-Legacy (berkas report.json) atau PBIR (folder \definition).

Untuk informasi selengkapnya, lihat dokumen skema definition.pbir.

mobileState.json

Berisi pengaturan tampilan dan perilaku laporan saat di-render pada perangkat seluler. File ini tidak mendukung pengeditan eksternal.

report.json

File ini berisi definisi laporan dalam format Power BI Report Legacy (PBIR-Legacy) dan tidak mendukung pengeditan eksternal.

folder definition\

Folder ini hanya tersedia jika proyek Power BI disimpan menggunakan format laporan Power BI yang ditingkatkan (PBIR). Ini menggantikan file report.json.

.platform

File platform Fabric yang menyimpan properti penting untuk membangun dan mempertahankan koneksi antara item Fabric dan Git.

Untuk mempelajari lebih lanjut, lihat Git integration automatically generated system files.

Format PBIR

Menyimpan file Proyek Power BI Anda (PBIP) menggunakan Format Laporan yang Ditingkatkan Power BI (PBIR) secara signifikan meningkatkan pelacakan perubahan dan resolusi konflik penggabungan dengan menggunakan file JSON yang diformat dengan benar.

Setiap halaman, visual, penanda buku, dll., diatur ke dalam file terpisah dan individual dalam struktur folder. Format ini sangat cocok untuk penyelesaian konflik dalam kerja sama pengembangan.

Tidak seperti PBIR-Legacy (report.json), PBIR adalah format yang didokumentasikan secara publik yang mendukung modifikasi dari aplikasi non-Power BI. Setiap file memiliki skema JSON publik, yang tidak hanya mendokumentasikan file tersebut tetapi juga memungkinkan editor kode seperti Visual Studio Code untuk melakukan validasi sintaks saat mengedit.

Beberapa skenario yang mungkin sekarang tersedia dengan PBIR termasuk:

• Salin halaman/visual/tanda halaman antar laporan.
• Pastikan konsistensi dari kumpulan tampilan visual di semua halaman dengan menyalin dan menempelkan berkas visual tersebut.
• Temukan dan ganti dengan mudah di berbagai file laporan.
• Terapkan pengeditan massal pada semua visual menggunakan skrip (misalnya, sembunyikan filter tingkat visual)

Simpan sebagai proyek menggunakan PBIR

Saat Anda menyimpan proyek menggunakan PBIR, laporan Anda disimpan dalam folder bernama \definition di dalam folder laporan:

Pelajari lebih lanjut tentang struktur folder PBIR.

Folder dan Berkas PBIR

Definisi laporan disimpan di dalam folder definition\ dengan struktur berikut:

├── 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	Diperlukan	Deskripsi
Penanda Buku	Tidak	Folder yang berisi semua file penanda halaman dari laporan.
── [bookmarkName].bookmark.json	Tidak	Metadata tanda buku, seperti visual target dan filter. Informasi lebih lanjut di schema.
── bookmarks.json	Tidak	Metadata penanda halaman, seperti urutan penanda halaman dan kelompok. Informasi lebih lanjut di schema.
halaman\	Ya	Map yang berisi semua halaman dari laporan.
── [namaHalaman]\	Ya	Satu folder per halaman.
──── visualisasi\	Tidak	Folder yang menyimpan semua visual dari halaman tersebut.
────── [visualName]\	Tidak	Satu folder per visual.
──────── mobile.json	Tidak	Metadata tata letak visual seluler, seperti posisi seluler dan pemformatan. Informasi lebih lanjut di schema.
─────── visual.json	Ya	Metadata visual, seperti posisi dan pemformatan, kueri. Informasi lebih lanjut di schema.
──── page.json	Ya	Metadata halaman, seperti penyaring tingkat halaman dan pemformatan. Informasi lebih lanjut di schema.
── pages.json	Tidak	Metadata halaman, seperti urutan halaman dan halaman aktif. Informasi lebih lanjut di schema.
version.json	Ya	Versi file PBIR, bersama faktor-faktor lainnya, menentukan file yang diperlukan untuk dimuat. Informasi selengkapnya di schema
reportExtensions.json	Tidak	Ekstensi laporan, seperti ukuran tingkat laporan. Informasi selengkapnya di schema
report.json	Ya	Metadata laporan, seperti filter tingkat laporan dan pemformatan. Informasi selengkapnya di schema

Penting

Beberapa file metadata laporan, seperti visual.json atau bookmarks.json, dapat disimpan dengan nilai data dari model semantik Anda. Misalnya, jika Anda menerapkan filter ke visual untuk bidang 'Perusahaan' = 'Contoso', nilai 'Contoso' akan bertahan sebagai bagian dari metadata. Ini juga berlaku untuk konfigurasi lain seperti pilihan pemotong, lebar kolom kustom matriks, dan pemformatan untuk seri tertentu.

Konvensi Penamaan PBIR

Semua nama di dalam tanda kurung siku ([]) pada tabel sebelumnya mengikuti konvensi penamaan default, tetapi dapat diganti dengan nama yang lebih mudah dipahami pengguna. Secara default, halaman, visual, dan penanda buku menggunakan nama objek laporan mereka sebagai nama file atau folder. Nama-nama objek ini awalnya adalah pengidentifikasi unik dengan 20 karakter, seperti '90c2e07d8e84e7d5c026'.

Pendukung untuk mengganti nama properti 'name' dalam setiap berkas JSON, tetapi mungkin memutuskan referensi eksternal baik di dalam maupun di luar laporan. Nama objek dan/atau nama file/folder harus terdiri dari satu atau lebih karakter kata (huruf, angka, garis bawah) atau tanda hubung.

Setelah mengganti nama berkas atau folder PBIR, Anda harus memulai ulang Power BI Desktop. Setelah memulai ulang, Power BI Desktop akan mempertahankan nama file atau folder asli saat menyimpan.

Salin nama objek laporan

Setiap objek dalam laporan disimpan dalam folder atau file terpisah, tetapi nama folder tidak selalu jelas. Untuk mempermudah ini, Anda bisa menyalin nama nama objek laporan apa pun (termasuk halaman, visual, marka buku, dan filter) langsung dari Power BI ke clipboard Anda.

Dari Desktop

1. Buka Opsi File > dan pengaturan Pengaturan laporan >> Laporkan objek dan aktifkan pengaturan Salin nama objek saat mengklik kanan pada pengaturan objek laporan . Ini hanya perlu dilakukan sekali.

   

2. Klik kanan pada objek laporan apa pun dan pilih Salin nama objek.

   

Dengan nama objek yang disalin ke clipboard, Anda dapat dengan mudah memasukkannya ke bilah pencarian Windows Explorer atau Visual Studio Code untuk menemukan atau mengidentifikasi nama objek dalam folder PBIR.

Dari layanan

1. Aktifkan pengaturan Salin nama objek saat mengklik kanan objek laporan . Ini hanya perlu dilakukan sekali. Anda tidak perlu mengaktifkannya untuk setiap laporan.

   

2. Saat mengedit laporan, klik kanan pada objek laporan apa pun dan pilih Salin nama objek.

   

Anda dapat menggunakan objek yang disalin untuk mengidentifikasi nama file dalam format file PBIR, atau untuk pemecahan masalah performa melalui Pemantauan Ruang Kerja atau Analitik Log untuk menautkan kueri DAX ke visual dalam laporan.

Skema PBIR Json

Setiap file JSON PBIR menyertakan deklarasi JSON schema di bagian atas dokumen. URL skema ini dapat diakses secara publik dan dapat digunakan untuk mengetahui lebih lanjut tentang properti dan objek yang tersedia untuk setiap file. Selain itu, ini menyediakan IntelliSense bawaan dan validasi saat mengedit dengan editor kode seperti Visual Studio Code.

URL skema juga menentukan versi dokumen, yang diharapkan akan berubah seiring dengan perkembangan definisi laporan.

Semua skema JSON diterbitkan di sini.

Anotasi PBIR

Anda dapat menyertakan anotasi sebagai pasangan nama-nilai dalam definisi laporan untuk setiap visual, page dan report. Meskipun Power BI Desktop mengabaikan anotasi ini, anotasi tersebut bisa berharga untuk aplikasi eksternal seperti skrip.

Misalnya, anda bisa menentukan defaultPage untuk laporan pada file report.json, yang kemudian dapat digunakan oleh skrip penyebaran.

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

Perubahan eksternal pada file PBIR

Anda dapat mengedit file JSON PBIR yang didukung di editor kode seperti Visual Studio Code atau alat eksternal lainnya saat proyek tetap terbuka di Power BI Desktop. Saat Anda menyimpan file, Power BI Desktop mendeteksi perubahan dan menampilkan banner Terapkan perubahan eksternal. Pilih Terapkan perubahan eksternal untuk memuat ulang definisi laporan tanpa menutup dan membuka kembali proyek.

Sebelum Anda mengedit file PBIR secara eksternal, simpan perubahan apa pun di Power BI Desktop. Jika Power BI Desktop memiliki perubahan yang belum disimpan saat Anda menerapkan perubahan eksternal, ini memperingatkan Anda bahwa perubahan yang belum disimpan akan ditimpa. Untuk alur kerja dan batasan lengkap, lihat Mengedit file PBIP di luar Power BI Desktop.

File PBIR harus sesuai dengan skema JSON mereka. Visual Studio Code mengidentifikasi masalah seperti nama properti yang tidak didukung atau jenis properti yang salah:

Perubahan eksternal pada konten PBIR mungkin mengakibatkan kesalahan saat Anda menerapkan perubahan atau membuka file di Power BI Desktop. Kesalahan ini bisa terdiri dari dua jenis:

Kesalahan pemblokiran mencegah Power BI Desktop memuat perubahan laporan. Kesalahan ini mengidentifikasi masalah dan file yang harus Anda perbaiki sebelum menerapkan perubahan lagi:

Kesalahan seperti skema yang tidak valid atau properti wajib yang hilang adalah kesalahan yang menghalangi proses. Untuk mengidentifikasi kesalahan ini, buka file di Visual Studio Code dan periksa pesan validasi skema.

Kesalahan non-blok tidak mencegah Power BI Desktop membuka laporan dan secara otomatis diselesaikan.

Konfigurasi yang tidak valid activePageName adalah contoh kesalahan nonblokir yang diperbaiki Power BI Desktop secara otomatis. Peringatan memberi Anda kesempatan untuk meninjau koreksi sebelum Anda menyimpan laporan dan menimpa definisi eksternal.

Kesalahan PBIR yang umum

Skenario:Setelah nama folder visual atau halaman diubah, visual atau halaman saya tidak lagi muncul saat membuka laporan.

Solusi: Verifikasi apakah nama sesuai dengan konvensi penamaan. Jika tidak, Power BI Desktop akan mengabaikan file atau folder tersebut dan menganggapnya sebagai file pengguna pribadi.

Skenario:Objek laporan baru diberi nama berbeda dari yang lain. Sebagai contoh, sebagian besar folder halaman diberi nama 'ReportSection0e71dafbc949c0853608', sementara beberapa yang lainnya diberi nama '1b3c2ab12b603618070b'.

Solusi: PBIR mengadopsi konvensi penamaan baru untuk setiap objek, tetapi ini hanya berlaku untuk objek baru. Saat Anda menyimpan laporan yang ada sebagai PBIP, nama-nama saat ini harus dipertahankan untuk mencegah terputusnya referensi. Jika Anda menginginkan konsistensi, skrip untuk mengganti nama batch diizinkan.

Skenario:Saya menyalin file penanda buku, dan setelah menyimpan, sebagian besar konfigurasi penanda buku tersebut terhapus.

Solusi: Perilaku ini memang disengaja, penanda laporan menangkap kondisi halaman laporan beserta semua visualnya. Karena kondisi yang diambil berasal dari halaman laporan lain dengan visual yang berbeda, visual yang tidak valid dihapus dari konfigurasi penanda halaman. Jika Anda juga menyalin visual dan halaman yang bergantung, penanda buku akan mempertahankan konfigurasinya.

Skenario:Saya menyalin folder halaman dari laporan lain dan menemukan kesalahan yang menyatakan, "Nilai untuk properti 'pageBinding.name' harus unik."

Solusi: Objek pageBinding diperlukan untuk mendukung drillthrough dan tooltip halaman. Karena mereka mungkin dirujuk oleh halaman lain, nama harus unik dalam laporan. Pada halaman yang baru disalin, tetapkan nilai unik untuk menyelesaikan kesalahan. Setelah Juni 2024, situasi ini tidak lagi menjadi masalah karena nama pageBinding secara default adalah GUID.

Ubah laporan yang ada menjadi PBIR

PBIR umumnya tersedia dan merupakan format laporan default. Anda masih dapat membuka laporan yang menggunakan PBIR-Legacy di Power BI Desktop dan layanan Power BI. Saat Anda mengedit dan menyimpan laporan PBIR-Legacy, Power BI secara diam-diam dan otomatis mengonversinya ke PBIR.

Sebelum konversi, Power BI membuat cadangan laporan:

• Power BI Desktop mempertahankan cadangan selama 30 hari di salah satu lokasi berikut:
  • Versi Microsoft Store: %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
  • Versi penginstal yang dapat dieksekusi: %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
• layanan Power BI mempertahankan cadangan PBIR-Legacy selama 28 hari. Untuk memulihkannya, buka Pengaturan laporan dari ruang kerja, dan pilih Pulihkan sebagai PBIR-Legacy. Cadangan ini dibuat hanya untuk laporan yang dikonversi langsung di layanan Power BI.

Memulihkan cadangan PBIR-Legacy tidak mencegah konversi lain. Untuk menyimpan laporan dalam format PBIR-Legacy, jangan mengeditnya di layanan Power BI, atau gunakan rilis Power BI Desktop yang dirilis sebelum September 2026.

Pertimbangan dan pembatasan PBIR

Ingatlah pertimbangan dan batasan berikut:

• Filter otomatis visual disimpan ke file PBIR visual.json hanya setelah panel filter diperluas setidaknya sekali saat mengedit laporan.
• Jika Power BI tidak mengonversi laporan PBIR-Legacy ke PBIR saat Anda mengedit dan menyimpannya, konversi mengalami masalah produk. Buat permintaan dukungan untuk melaporkan masalah.

Batasan ukuran PBIR yang diberlakukan oleh layanan:

• 1.000 halaman maksimal per laporan.
• 1000 visual maks per halaman.
• 1.000 file paket sumber daya maks per laporan.
• Ukuran maksimum 300 mb untuk semua file paket sumber daya.
• Ukuran maksimum 300 mb dari semua file laporan.

Penting

Jika Anda mencapai batas di atas, Anda harus mempertimbangkan untuk mengoptimalkan laporan Anda. Lihat dokumen Pengoptimalan Power BI.

Integrasi Git Fabric dan API REST Fabric mengekspor definisi laporan menggunakan PBIR.

Konten terkait

• Folder model semantik proyek Power BI Desktop
• Proyek Power BI Desktop