Power BI ビジュアルの機能とプロパティ

[アーティクル]
02/21/2024

すべての視覚化には 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 ファイルに次のルートオブジェクトが含まれます。

privileges
dataRoles
dataViewMappings
objects

上記のオブジェクトはデータバインディングに必要なオブジェクトです。ビジュアルにとって必要であれば編集できます。

次の追加ルートオブジェクトは省略可能であり、必要に応じて追加できます。

すべてのオブジェクトとそのパラメーターは capabilities.json スキーマにあります。

特権: 視覚化に必要な、特殊なアクセス許可を定義します

特権は、操作するために視覚化からアクセスする特殊な操作です。特権は privilege オブジェクトの配列を受け取ります。ここにすべての特権プロパティが定義されています。以下のセクションでは、Power BI で使用できる特権について説明します。

注意

API v4.6.0 以降、特権は capabilities.json ファイルで指定する必要があります。それより前のバージョンでは、リモートアクセスは自動的に許可され、ファイルにはダウンロードできません。使用しているバージョンを確認するには、pbiviz.json ファイルの apiVersion を確認してください。

特権を定義する

JSON の特権定義には、次のコンポーネントが含まれています。

name - (文字列) 特権の名前。
essential - (ブール値) 視覚化の機能にこの特権が必要かどうかを示します。 true の値は特権が必要であることを意味し、false は特権が必要でないことを意味します。
parameters - (文字列配列)(省略可能) 引数。 parameters がない場合は、空の配列と見なされます。

次の種類の特権を定義する必要があります。

外部リソースにアクセスする
ファイルにダウンロードする
ローカルストレージ特権

Note

視覚化でこれらの特権を付与した場合でも、管理者は、組織内のユーザーがこれらの設定の恩恵を受けられるように、管理者設定でこのスイッチを有効にする必要があります。

Web アクセスを許可する

外部リソースや Web サイトへのアクセスを視覚化に許可するには、この情報を "特権" として capabilities セクションに追加します。特権の定義には、視覚化にアクセスを許可する URL の省略可能な一覧を http://xyz.com または https://xyz.com の形式で指定できます。各 URL にはサブドメインを指定するワイルドカードを含めることもできます。

外部リソースへのアクセスを許可する特権設定の例を次の示します。

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

上の WebAccess 特権は、視覚化が、microsoft.com ドメインの任意のサブドメインには HTTPS プロトコル経由のみ、サブドメインなしの 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 プロパティ

DataRole は次のプロパティによって定義されます。

name:このデータフィールドの内部名 (一意である必要があります)。
displayName: プロパティ ウィンドウでユーザーに表示される名前。
kind: フィールドの種類:
- Grouping: メジャーフィールドをグループ化するために使用される不連続値のセット。
- Measure: 1 つの数値。
- GroupingOrMeasure:グループ化またはメジャーのいずれかとして使用できる値。
description: フィールドの短いテキストの説明 (省略可能)。
requiredTypes: このデータロールに必要なデータの型。一致しない値は null に設定されます (省略可能)。
preferredTypes: このデータロールで優先されるデータの型 (省略可能)。

requiredTypes と preferredTypes で有効なデータ型

bool: ブール値
integer: 整数値
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
            }
        ]
    }
]
...
}

前のデータロールでは、次の画像に示すフィールドが作成されます。

Data role fields

dataViewMappings: データのマップ方法

dataViewMappings オブジェクトには、データロールが相互にどのように関連しているかが記述され、ユーザーがデータビューを表示する条件付き要件を指定できます。

ほとんどのビジュアルでは 1 つのマッピングが提供されますが、複数の dataViewMapping を指定することができます。有効なマッピングごとにデータビューが生成されます。

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

詳細については、「Power BI ビジュアルでのデータビューのマッピングについて理解する」を参照してください。

objects: プロパティペインのオプションを定義する

オブジェクトでは、ビジュアルに関連付けられているカスタマイズ可能なプロパティを記述します。このセクションで定義されているオブジェクトは、[書式] ペインに表示されるオブジェクトです。各オブジェクトには複数のプロパティを含めることができ、各プロパティにはそれに関連付けられた型があります。

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

たとえば、カスタムビジュアルで動的書式指定文字列をサポートするには、次のオブジェクトを定義してください。

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

詳細については、「Power BI ビジュアルのオブジェクトとプロパティ」を参照してください。

Power BI ビジュアルの機能とプロパティ

特権: 視覚化に必要な、特殊なアクセス許可を定義します

特権を定義する

Web アクセスを許可する

ファイルにダウンロードする

ローカルストレージ特権

特権は不要

複数の特権

dataRoles: ビジュアルに必要なデータフィールドを定義する

DataRole プロパティ

requiredTypes と preferredTypes で有効なデータ型

dataRoles の例

dataViewMappings: データのマップ方法

objects: プロパティペインのオプションを定義する

フィードバック

フィードバック

その他のリソース

Power BI ビジュアルの機能とプロパティ

特権: 視覚化に必要な、特殊なアクセス許可を定義します

特権を定義する

Web アクセスを許可する

ファイルにダウンロードする

ローカル ストレージ特権

特権は不要

複数の特権

dataRoles: ビジュアルに必要なデータ フィールドを定義する

DataRole プロパティ

requiredTypes と preferredTypes で有効なデータ型

dataRoles の例

dataViewMappings: データのマップ方法

objects: プロパティ ペインのオプションを定義する

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

ローカルストレージ特権

dataRoles: ビジュアルに必要なデータフィールドを定義する

objects: プロパティペインのオプションを定義する