閱讀英文

共用方式為


Power BI 視覺效果的功能和屬性

每個視覺效果都有一個 capabilities.json 檔案,當您執行 pbiviz new <visual project name> 命令以建立新的視覺效果時,就會自動建立此檔案。 capabilities.json 檔案描述主機的視覺效果。

capabilities.json 檔案會告知主機視覺效果所接受的資料種類、要放在屬性窗格上的可自訂屬性,以及建立視覺效果所需的其他資訊。 從 API v4.6.0 開始,功能模型上的所有屬性都是「選用」屬性,但 privileges 除外,其是「必要」屬性。

capabilities.json 檔案會以下列格式列出根物件:

JSON
{
    "privileges": [ ... ],
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
    ...
}

當您建立新的視覺效果時,預設 capabilities.json 檔案包含下列根物件:

上述物件是資料繫結所需的物件。 其可以視需要針對您的視覺效果進行編輯。

下列其他根物件是選用的,您可以視需要新增這些物件:

您可以在 capabilities.json 結構描述中找到所有這些物件及其參數

privileges:定義視覺效果所需的特殊權限

權限是視覺效果需要存取才能運作的特殊作業。 權限接受 privilege 物件的陣列,其會定義所有權限屬性。 以下幾節描述可在 Power BI 中使用的權限。

注意

從 API v4.6.0 起,「必須」capabilities.json 檔案中指定權限。 在舊版中,會自動授與遠端存取權,但無法將其下載至檔案。 若要了解您正在使用哪個版本,請檢查 pbiviz.json 檔案中的 apiVersion

定義權限

JSON 權限定義包含下列元件:

  • name - (字串) 權限的名稱。
  • essential - (布林值) 指出視覺效果功能是否需要此權限。 true 值表示需要權限;false 表示權限並非必要。
  • parameters - (字串陣列) (選用) 引數。 如果遺漏 parameters,則會將其視為空陣列。

以下是必須定義的權限類型:

注意

即使在視覺效果中授與了這些權限,系統管理員仍必須啟用系統管理員設定中的切換,以允許組織中的人員受益於這些設定。

允許 Web 存取

若要允許視覺效果存取外部資源或網站,請將該資訊新增為功能區段中的「權限」。 權限定義包含允許視覺效果以 http://xyz.comhttps://xyz.com 格式存取的選用 URL 清單。 每個 URL 也可以包含萬用字元來指定子網域。

下列程式碼是允許存取外部資源的權限設定範例:

JSON
{
    "name": "WebAccess",
    "essential": true,
    "parameters": [ "https://*.microsoft.com", "http://example.com" ]
}

上述 WebAccess 權限表示視覺效果必須只透過 HTTPS 通訊協定存取 microsoft.com 網域的任何子域,以及透過 HTTP 存取沒有子網域的 example.com,並表示此存取權限對於視覺效果若要運作至關重要。

下載成檔案

若要允許使用者將資料從視覺效果匯出至檔案,請將 ExportContent 設定為 true

ExportContent 設定可讓視覺效果以下列格式將資料匯出至檔案:

  • .txt
  • .csv
  • .json
  • .tmplt
  • .xml
  • .pdf
  • .xlsx

這是獨立設定,不受組織的匯出及共用租用戶設定中所套用的下載限制影響。

下列程式碼是允許下載至檔案的權限設定範例:

JSON
"privileges": [
    {
        "name": "ExportContent",
        "essential": true
    }
]

本機存放區屬性

此權限可讓自訂視覺效果在使用者的本機瀏覽器上儲存資訊。

下列程式碼是允許使用本機存放區的權限設定範例:

JSON
"privileges": [
    {
        "name": "LocalStorage",
        "essential": true
    }
]

不需要任何權限

如果視覺效果不需要任何特殊權限,則 privileges 陣列應該是空的:

JSON
  "privileges": []

多個權限

下列範例會示範如何為自訂視覺效果設定數個權限。

JSON
"privileges": [
    {
        "name": "WebAccess",
        "essential": true,
        "parameters": [ "https://*.virtualearth.net" ]
    },
    {
        "name": "ExportContent",
        "essential": false
    }
]

dataroles:定義視覺效果預期的資料欄位

若要定義可以繫結至資料的欄位,請使用 dataRolesdataRolesDataViewRole 物件的陣列,其會定義所有必要的屬性。 dataRoles 物件是出現在屬性窗格上的 [欄位]

使用者會將資料欄位拖曳至其中,以將資料欄位繫結至物件。

DataRole 屬性

使用下列內容定義 DataRoles:

  • name:此資料欄位的內部名稱 (必須是唯一)。
  • displayName:在 [屬性] 窗格中顯示給使用者的名稱。
  • kind:欄位種類:
    • Grouping:一組用來將量值欄位分組的離散值。
    • Measure:單一數值。
    • GroupingOrMeasure:可以當作分組或量值使用的值。
  • description:欄位的簡短文字描述 (選用)。
  • requiredTypes:此資料角色所需的資料類型。 任何不符合的值都會設定為 Null (選擇性)。
  • preferredTypes:此資料角色慣用的資料類型 (選用)。

requiredTypes 和 preferredTypes 的有效資料類型

  • bool:布林值
  • integer:整數值
  • numeric:數值
  • text:文字值
  • geography:地理資料

dataRoles 範例

JSON
"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
            }
        ]
    }
]
...
}

上述資料角色會建立顯示在下列影像中的欄位:

資料角色欄位

dataViewMappings:定義您要對應資料的方式

dataViewMappings 物件會描述資料角色的相互關係,並可讓您指定顯示資料檢視的條件式需求。

大部分的視覺效果都提供單一對應,但您可以提供多個 dataViewMappings。 每個有效對應都會產生資料檢視。

JSON
"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

如需詳細資訊,請參閱了解 Power BI 視覺效果中的資料檢視對應

objects:定義屬性窗格選項

Objects 描述與視覺效果相關聯的可自訂屬性。 本節中定義的物件是出現在格式窗格中的物件。 每個物件都可以具有多個屬性,而且每個屬性都有一個與其相關聯的類型。

JSON
"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

例如,若要在自訂視覺效果中支援動態格式字串,請定義下列物件:

JSON
"objects": {
        "general": {
            "properties": {
                "formatString": {
                    "type": {
                        "formatting": {
                            "formatString": true
                        }
                    }
                }
            }
        },

如需詳細資訊,請參閱 Power BI 視覺效果的物件和屬性