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:

• Hak istimewa
• dataRoles
• dataViewMappings
• Objek

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
• pengurutan
• telusuri lebih dalam
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• subtotals
• keepAllMetadataColumns
• migrasi

Anda dapat menemukan semua objek ini dan parameternya dalam skema capabilities.json

hak istimewa: tentukan izin khusus yang diperlukan oleh visual Anda

Hak akses khusus adalah operasi khusus yang perlu diakses oleh visual Anda agar dapat berfungsi. Hak akses menerima array objek privilege, yang mendefinisikan semua properti hak akses. 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 akses istimewa.
• essential - (Boolean) Menunjukkan apakah fungsionalitas visual memerlukan hak istimewa ini. Nilai true berarti hak istimewa diperlukan; false berarti hak istimewa tidak wajib.
• parameters - (array string)(opsional) Argumen. Jika parameters hilang, array tersebut dianggap sebagai array kosong.

Berikut ini adalah jenis hak istimewa yang harus ditentukan:

• Mengakses sumber daya Eksternal
• Unduh ke file
• Hak istimewa penyimpanan lokal

Catatan

Bahkan jika izin ini telah diberikan dalam visual ini, admin tetap harus mengaktifkan opsi tersebut di pengaturan admin agar orang di organisasinya dapat memanfaatkan 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
• .pdf
• .xlsx

Pengaturan ini terpisah dari pembatasan unduhan yang diterapkan pada pengaturan tenant ekspor dan berbagi organisasi dan tidak terpengaruh olehnya.

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 Anda ikat ke data, gunakan 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.

Konten terkait

• Memahami pemetaan tampilan data dalam visual Power BI
• Objek dan properti visual Power BI
• Opsi pengurutan untuk visual Power BI