共用方式為

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

  • 發行項

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

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

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

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

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

上述對像是數據系結所需的物件。 您可以視需要編輯視覺效果。

下列其他根對象是選擇性的，可以視需要新增：

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

許可權：定義視覺效果所需的特殊許可權

許可權是視覺效果需要存取才能運作的特殊作業。 許可權會採用 物件的陣列，此陣列 privilege 會定義所有許可權屬性。 下列各節說明 Power BI 中可用的許可權。

注意

從 API v4.6.0 中，必須在 capabilities.json 檔案中指定許可權。 在舊版中，會自動授與遠端訪問，而且無法下載至檔案。 若要找出您使用的版本，請在 pbiviz.json 檔案中籤apiVersion入 。

定義許可權

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

  • name - （字串） 權限的名稱。
  • essential - （布爾值） 指出視覺功能是否需要此許可權。 的值 true 表示需要許可權; false 表示許可權並非必要。
  • parameters - （字串陣列）（選擇性） 自變數。 如果 parameters 遺失，則會將其視為空陣列。

以下是必須定義的權限型態：

注意

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

允許 Web 存取

若要允許視覺效果存取外部資源或網站，請將該資訊新增為 功能區段中的許可權 。 許可權定義包含允許視覺效果以 或https://xyz.com格式http://xyz.com存取的選擇性 URL 清單。 每個 URL 也可以包含通配符來指定子域。

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

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

上述 WebAccess 許可權表示視覺效果必須只透過 HTTPS 通訊協定存取網域的任何子域 microsoft.com ，而 example.com 不需要透過 HTTP 存取子域，而且此存取許可權對於視覺效果而言至關重要。

下載成檔案

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

這個 ExportContent 設定可讓視覺效果以下欄格式將資料匯出至檔案：

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

此設定與組織匯出和共用租用戶設定中套用的下載限制不同，且不受影響。

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

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

本機記憶體許可權

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

以下是允許使用本機記憶體的許可權設定範例：

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

不需要任何許可權

如果視覺效果不需要任何特殊許可權，陣列應該是空的 privileges ：

  "privileges": []

多個許可權

下列範例示範如何設定自定義視覺效果的數個許可權。

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

dataroles：定義視覺效果預期的數據欄位

若要定義可以繫結至資料的欄位，您可以使用 dataRoles。 dataRoles 是對象的陣列 DataViewRole ，定義所有必要的屬性。 對像是dataRoles出現在 [屬性] 窗格上的欄位。

使用者會將數據欄位拖曳到其中，將數據欄位系結至物件。

DataRole 屬性

使用下列屬性定義 DataRoles：

  • name：此數據欄位的內部名稱（必須是唯一的）。
  • displayName：在 [屬性] 窗格中向用戶顯示的名稱。
  • kind：欄位種類：
    • Grouping：用來將量值欄位分組的離散值集合。
    • Measure：單一數值。
    • GroupingOrMeasure：可用來做為群組或量值的值。
  • description：字段的簡短文字描述（選擇性）。
  • requiredTypes：此數據角色的必要數據類型。 不符合的值會設定為 null（選擇性）。
  • preferredTypes：此數據角色的慣用數據類型（選擇性）。

requiredTypes 和 preferredTypes 的有效數據類型

  • bool：布爾值
  • 整數：整數值
  • numeric：數值
  • text：文字值
  • geography：地理數據

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

上述資料角色會建立如下圖所示的欄位：

數據角色欄位

dataViewMappings：您想要如何對應數據

物件 dataViewMappings 描述數據角色如何彼此關聯，並可讓您指定顯示數據檢視的條件式需求。

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

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

如需詳細資訊，請參閱 瞭解Power BI視覺效果中的數據檢視對應。

objects：定義屬性窗格選項

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

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

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

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

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

相關內容