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

• privileges
• dataRoles
• dataViewMappings
• objects

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

以下に示すその他のルート オブジェクトはオプションであり、必要に応じて追加できます。

• tooltips
• supportsHighlight
• sorting
• drilldown
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• 小計
• keepAllMetadataColumns
• migration

すべてのオブジェクトとそのパラメーターは 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 プロパティ

以下のプロパティを使用して DataRoles を定義します。

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

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

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 ビジュアルでのデータ ビューのマッピングについて理解する
• Power BI ビジュアルのオブジェクトとプロパティ
• Power BI ビジュアルの並べ替えオプション