Возможности и свойства визуальных элементов Power BI

Каждый визуальный элемент имеет capabilities.json файл, который создается автоматически при выполнении pbiviz new <visual project name> команды для создания нового визуального элемента. Файл capabilities.json описывает визуальный компонент для хоста.

Файл capabilities.json сообщает узлу, какой вид данных принимает визуальный элемент, какие настраиваемые атрибуты следует поместить в область свойств, а также другие сведения, необходимые для создания визуального элемента. Начиная с API версии 4.6.0 все свойства модели возможностей являются необязательными, за исключением privilegesнеобходимых.

В файле capabilities.json перечислены корневые объекты в следующем формате:

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

При создании нового визуального элемента файл по умолчанию capabilities.json включает следующие корневые объекты:

• Привилегии
• dataRoles
• dataViewMappings
• объекты

Приведенные выше объекты являются теми, которые необходимы для привязки данных. Их можно при необходимости отредактировать для вашего визуального материала.

Следующие другие корневые объекты являются необязательными и могут быть добавлены по мере необходимости:

• подсказки
• поддерживает выделение
• сортировка
• детализация
• expandCollapse
• поддерживает фокус с клавиатуры
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• Промежуточные итоги
• keepAllMetadataColumns
• миграция

Все эти объекты и их параметры можно найти в схеме capabilities.json

привилегии: определите специальные разрешения, необходимые визуальному элементу.

Привилегии — это специальные операции, доступ к которым необходим вашей визуализации для работы. Привилегии принимают массив объектов privilege, задающих все свойства привилегий. В следующих разделах описаны привилегии, доступные в Power BI.

Примечание.

В API версии 4.6.0 в файле capabilities.json необходимо указать привилегии. В более ранних версиях удаленный доступ предоставляется автоматически, а скачивание в файл невозможно. Чтобы узнать, какую версию вы используете, проверьте apiVersion в файле pbiviz.json.

Определение привилегий

Определение привилегий JSON содержит следующие компоненты:

• name — (строка) Имя привилегии.
• essential — (логическое значение) Указывает, требует ли эта визуальная функция данной привилегии. Значение true означает, что требуется привилегия. false Это означает, что привилегия не является обязательной.
• parameters — (строковый массив)(необязательно) Аргументы. Если parameters отсутствует, он считается пустым массивом.

Ниже перечислены типы привилегий, которые должны быть определены.

• Доступ к внешним ресурсам
• Скачать в файл
• Права локального хранилища

Примечание.

Даже с этими привилегиями, предоставленными в визуальном элементе, администратор должен включить переключатель в параметрах администратора, чтобы позволить пользователям в своей организации воспользоваться этими параметрами.

Разрешить веб-доступ

Чтобы разрешить визуальному элементу доступ к внешнему ресурсу или веб-сайту, добавьте эти сведения в качестве привилегии в разделе возможностей. Определение привилегий включает необязательный список 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, и что это право доступа необходимо для работы визуального элемента.

Скачивание в файл

Чтобы разрешить пользователю экспортировать данные из визуального элемента в файл, задайте значение ExportContenttrue.

Этот 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 со следующими свойствами:

• имя: внутреннее имя этого поля данных (должно быть уникальным).
• displayName: имя, отображаемое пользователю в области свойств .
• kind: тип поля:
  • Grouping: набор дискретных значений, используемых для группирования полей мер.
  • Measure: одночисленные числовые значения.
  • GroupingOrMeasure: значения, которые можно использовать либо для группировки, либо как меру.
• описание: краткое текстовое описание поля (необязательно).
• requiredTypes: обязательный тип данных для этой роли данных. Значения, которые не совпадают, имеют значение NULL (необязательно).
• preferredTypes: предпочтительный тип данных для этой роли данных (необязательно).

Допустимые типы данных для обязательных типов и предпочитаемых Типов

• bool: логическое значение
• целое число: целочисленное значение
• числовой: Числовое значение
• текст: текстовое значение
• география: географические данные

Пример 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 описывают связь ролей данных друг с другом и позволяют указать условные требования для отображения представлений данных.

Большинство визуальных элементов предоставляют одно сопоставление, но можно предоставить несколько данныхViewMappings. Каждое допустимое сопоставление создает представление данных.

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

Дополнительные сведения см. в статье Сведения о сопоставлении представлений данных в визуальных элементах Power BI.

объекты: определение параметров области свойств

Объекты описывают настраиваемые свойства, связанные с визуальным элементом. Объекты, определенные в этом разделе, — это объекты, которые отображаются в области "Формат". Каждый объект может иметь несколько свойств, и каждое свойство имеет тип, связанный с ним.

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

Например, чтобы поддерживать строки динамического формата в пользовательском визуальном элементе, определите следующий объект:

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

Дополнительные сведения см. в разделе "Объекты и свойства визуальных элементов Power BI".

Связанный контент

• Общие сведения о сопоставлении представлений данных в визуальных элементах Power BI
• Объекты и свойства визуальных элементов Power BI
• Параметры сортировки визуальных элементов Power BI