Kemampuan dan properti visual Power BI
Setiap visual memiliki file capabilities.json yang dibuat secara otomatis saat Anda menjalankan pbiviz new <visual project name>
perintah untuk membuat visual baru. File capabilities.json menjelaskan visual ke host.
File capabilities.json memberi tahu host jenis data apa yang diterima visual, atribut apa yang dapat disesuaikan untuk diletakkan di panel properti, dan informasi lain yang diperlukan untuk membuat visual. Mulai dari API v4.6.0, semua properti pada model kemampuan bersifat opsional kecuali privileges
, yang diperlukan.
File capabilities.json mencantumkan objek akar dalam format berikut:
{
"privileges": [ ... ],
"dataRoles": [ ... ],
"dataViewMappings": [ ... ],
"objects": { ... },
"supportsHighlight": true|false,
"advancedEditModeSupport": 0|1|2,
"sorting": { ... }
...
}
Saat Anda membuat visual baru, file capabilities.json default menyertakan objek akar berikut:
Objek di atas adalah objek yang diperlukan untuk pengikatan data. Mereka dapat diedit seperlunya untuk visual Anda.
Objek akar lainnya berikut bersifat opsional dan dapat ditambahkan sesuai kebutuhan:
- tooltips
- supportsHighlight
- sorting
- telusuri paling detail
- expandCollapse
- supportsKeyboardFocus
- supportsSynchronizingFilterState
- advancedEditModeSupport
- supportsLandingPage
- supportsEmptyDataView
- supportsMultiVisualSelection
- subtotals
- keepAllMetadataColumns
- migrasi
Anda dapat menemukan semua objek ini dan parameternya dalam skema capabilities.json
hak istimewa: menentukan izin khusus yang diperlukan visual Anda
Hak istimewa adalah operasi khusus yang memerlukan akses visual Anda untuk beroperasi. Hak istimewa mengambil array privilege
objek, yang menentukan semua properti hak istimewa. Bagian berikut ini menjelaskan hak istimewa yang tersedia di Power BI.
Catatan
Dari API v4.6.0, hak istimewa harus ditentukan dalam file capabilities.json. Dalam versi sebelumnya, akses jarak jauh secara otomatis diberikan dan mengunduh ke file tidak dimungkinkan. Untuk mengetahui versi mana yang Anda gunakan, periksa apiVersion
di file pbiviz.json .
Tentukan hak istimewa
Definisi hak istimewa JSON berisi komponen-komponen ini:
name
- (string) Nama hak istimewa.essential
- (Boolean) Menunjukkan apakah fungsionalitas visual memerlukan hak istimewa ini. Nilaitrue
berarti hak istimewa diperlukan;false
berarti hak istimewa tidak wajib.parameters
- (array string)(opsional) Argumen. Jikaparameters
hilang, array tersebut dianggap sebagai array kosong.
Berikut ini adalah jenis hak istimewa yang harus ditentukan:
Catatan
Bahkan dengan hak istimewa ini diberikan dalam visual, admin harus mengaktifkan pengalihan di pengaturan admin untuk memungkinkan orang-orang di organisasi mereka mendapatkan manfaat dari pengaturan ini.
Perbolehkan akses web
Untuk mengizinkan visual mengakses sumber daya eksternal atau situs web, tambahkan informasi tersebut sebagai hak istimewa di bagian kemampuan. Definisi hak istimewa mencakup daftar URL opsional yang diizinkan untuk diakses visual dalam format http://xyz.com
atau https://xyz.com
. Setiap URL juga dapat menyertakan kartubebas untuk menentukan subdomain.
Kode berikut adalah contoh pengaturan hak istimewa yang memungkinkan akses ke sumber daya eksternal:
{
"name": "WebAccess",
"essential": true,
"parameters": [ "https://*.microsoft.com", "http://example.com" ]
}
Hak istimewa sebelumnya WebAccess
berarti bahwa visual perlu mengakses subdomain microsoft.com
domain apa pun melalui protokol HTTPS saja dan example.com
tanpa subdomain melalui HTTP, dan bahwa hak istimewa akses ini sangat penting agar visual berfungsi.
Unduh ke file
Untuk mengizinkan pengguna mengekspor data dari visual ke dalam file, atur ExportContent
ke true
.
Pengaturan ini ExportContent
memungkinkan visual untuk mengekspor data ke file dalam format berikut:
- .txt
- .csv
- .json
- .tmplt
- .xml
- .xlsx
Pengaturan ini terpisah dari dan tidak terpengaruh oleh pembatasan unduhan yang diterapkan dalam pengaturan penyewa ekspor dan berbagi organisasi.
Kode berikut adalah contoh pengaturan hak istimewa yang memungkinkan pengunduhan ke file:
"privileges": [
{
"name": "ExportContent",
"essential": true
}
]
Hak istimewa penyimpanan lokal
Hak istimewa ini memungkinkan visual kustom untuk menyimpan informasi di browser lokal pengguna.
Berikut ini adalah contoh pengaturan hak istimewa yang memungkinkan penggunaan penyimpanan lokal:
"privileges": [
{
"name": "LocalStorage",
"essential": true
}
]
Tidak diperlukan hak istimewa
Jika visual tidak memerlukan izin khusus, privileges
array harus kosong:
"privileges": []
Beberapa hak istimewa
Contoh berikut menunjukkan cara mengatur beberapa hak istimewa untuk visual kustom.
"privileges": [
{
"name": "WebAccess",
"essential": true,
"parameters": [ "https://*.virtualearth.net" ]
},
{
"name": "ExportContent",
"essential": false
}
]
dataroles: menentukan bidang data yang diharapkan visual Anda
Untuk menentukan bidang yang dapat terikat ke data, Anda menggunakan dataRoles
. dataRoles
adalah array objek DataViewRole
, yang mendefinisikan semua properti yang diperlukan. Objek dataRoles
adalah bidang yang muncul di panel Properti.
Pengguna menyeret bidang data ke dalamnya untuk mengikat data bidang data ke objek.
Properti DataRole
Tentukan DataRoles dengan properti berikut:
- name: Nama internal bidang data ini (harus unik).
- displayName: Nama yang ditampilkan kepada pengguna di panel Properti.
- jenis: Jenis bidang:
Grouping
: Kumpulan nilai diskrit yang digunakan untuk mengelompokkan bidang pengukuran.Measure
: Nilai numerik tunggal.GroupingOrMeasure
: Nilai yang dapat digunakan sebagai pengelompokan atau pengukuran.
- description: Deskripsi teks singkat dari bidang (opsional).
- requiredTypes: Jenis data yang diperlukan untuk peran data ini. Nilai yang tidak cocok diatur ke null (opsional).
- preferredTypes: Jenis data pilihan untuk peran data ini (opsional).
Jenis data yang valid untuk requiredTypes dan preferredTypes
- bool: Nilai boolean
- integer: Nilai bilangan bulat
- numeric: Nilai numerik
- text: Nilai teks
- geography: Data geografis
contoh dataRoles
"dataRoles": [
{
"displayName": "My Category Data",
"name": "myCategory",
"kind": "Grouping",
"requiredTypes": [
{
"text": true
},
{
"numeric": true
},
{
"integer": true
}
],
"preferredTypes": [
{
"text": true
}
]
},
{
"displayName": "My Measure Data",
"name": "myMeasure",
"kind": "Measure",
"requiredTypes": [
{
"integer": true
},
{
"numeric": true
}
],
"preferredTypes": [
{
"integer": true
}
]
}
]
...
}
Peran data sebelumnya akan membuat bidang yang ditampilkan dalam gambar berikut:
dataViewMappings: bagaimana Anda ingin data dipetakan
Objek dataViewMappings
menjelaskan bagaimana peran data berhubungan satu sama lain dan memungkinkan Anda menentukan persyaratan kondisi untuk tampilan data yang ditampilkan.
Sebagian besar visual menyediakan satu pemetaan, tetapi Anda dapat menyediakan beberapa dataViewMappings. Setiap pemetaan yang valid menghasilkan tampilan data.
"dataViewMappings": [
{
"conditions": [ ... ],
"categorical": { ... },
"table": { ... },
"single": { ... },
"matrix": { ... }
}
]
Untuk informasi selengkapnya, lihat Memahami pemetaan tampilan data di visual Power BI.
objek: menentukan opsi panel properti
Objek menjelaskan properti yang dapat disesuaikan yang terkait dengan visual. Objek yang ditentukan di bagian ini adalah objek yang muncul di panel Format. Setiap objek dapat memiliki beberapa properti, dan setiap properti memiliki jenis yang terkait dengannya.
"objects": {
"myCustomObject": {
"properties": { ... }
}
}
Misalnya, untuk mendukung string format dinamis dalam visual kustom Anda, tentukan objek berikut:
"objects": {
"general": {
"properties": {
"formatString": {
"type": {
"formatting": {
"formatString": true
}
}
}
}
},
Untuk informasi selengkapnya, lihat Objek dan properti visual Power BI.