Возможности и свойства визуальных элементов 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
• Объектов

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

Примечание.

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

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

Чтобы разрешить визуальному элементу доступ к внешнему ресурсу или веб-сайту, добавьте эти сведения в качестве привилегии в разделе возможностей. Определение привилегий включает необязательный список URL-адресов, к которым визуальный элемент может получить доступ в формате http://xyz.com или https://xyz.com. Каждый URL-адрес также может содержать подстановочный знак для указания поддоменов.

Следующий код является примером параметров привилегий, позволяющих получить доступ к внешним ресурсам:

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

Предыдущая WebAccess привилегия означает, что визуальный элемент должен получить доступ к любому поддомену домена через протокол HTTPS только и example.com без поддоменов microsoft.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 со следующими свойствами:

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