Funcionalidades y propiedades de objetos visuales de Power BI

Cada objeto visual tiene un archivo capabilities.json que se crea automáticamente al ejecutar el comando pbiviz new <visual project name> para crear un nuevo objeto visual. El archivo capabilities.json describe el objeto visual para el host.

En el archivo capabilities.json, se indica al host qué tipo de datos acepta el objeto visual, qué atributos personalizables se deberán colocar en el panel de propiedades y otra información necesaria para crear el objeto visual. A partir de la API v4.6.0, todas las propiedades del modelo de funcionalidades son opcionales, excepto los privileges, que son obligatorios.

El archivo capabilities.json enumera los objetos raíz con el siguiente formato:

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

Cuando se crea un objeto visual, el archivo capabilities.json predeterminado incluye los siguientes objetos raíz:

• privileges
• dataRoles
• dataViewMappings
• objects

Los objetos anteriores son los necesarios para el enlace de datos. Se pueden editar según se requiera para el objeto visual.

Los siguientes objetos raíz son opcionales y pueden añadirse según sea necesario:

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

Puede encontrar todos estos objetos y sus parámetros en el esquema capabilities.json

privileges: definen los permisos especiales que requiere el objeto visual.

Los privilegios son operaciones especiales a las que el objeto visual requiere acceso para poder operar. Los privilegios toman una matriz de objetos privilege que define todas sus propiedades. En las secciones siguientes, se describen los privilegios que están disponibles en Power BI.

Nota

Desde la API v4.6.0, los privilegios deben especificarse en el archivo capabilities.json. En versiones anteriores, el acceso remoto se concede automáticamente y no se puede descargar en archivos. Para averiguar qué versión usa, compruebe apiVersion en el archivo pbiviz.json.

Definición de privilegios

Una definición de privilegios de JSON contiene estos componentes:

• name: cadena, nombre del privilegio.
• essential: valor booleano que indica si la funcionalidad del objeto visual requiere este privilegio. Un valor de true significa que se requiere el privilegio; false significa que el privilegio no es obligatorio.
• parameters: matriz de cadenas opcional para argumentos. Si falta parameters, se considera una matriz vacía.

A continuación se muestran los tipos de privilegios que se deben definir:

• Acceso a recursos externos
• Descarga en un archivo
• Privilegios de almacenamiento local

Nota:

Incluso con estos privilegios concedidos al objeto visual, el administrador debe habilitar el cambio en la configuración de administración para que las personas de su organización se puedan beneficiar de esta configuración.

Permitir el acceso a la Web

Para permitir que un objeto visual acceda a un recurso externo o un sitio web, agregue esa información como un privilegio en la sección de funcionalidades. La definición de privilegios incluye una lista opcional de direcciones URL a las que el objeto visual puede tener acceso con el formato http://xyz.com o https://xyz.com. Cada dirección URL puede incluir también un carácter comodín para especificar subdominios.

El siguiente código es un ejemplo de configuración de privilegios que permite el acceso a recursos externos:

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

El privilegio WebAccess anterior significa que el objeto visual debe tener acceso a cualquier subdominio del dominio microsoft.com solo a través del protocolo HTTPS y example.com sin subdominios a través de HTTP, y que este privilegio de acceso es esencial para que el objeto visual funcione.

Descarga en un archivo

Para permitir que el usuario exporte datos de un objeto visual a un archivo, establezca ExportContent en true.

ExportContent permite que el objeto visual exporte datos a archivos con los siguientes formatos:

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

Esta opción de configuración es independiente de las restricciones de descarga aplicadas en la Configuración de exportación y uso compartido del inquilino de la organización, que no le afectan.

El siguiente código es un ejemplo de una configuración de privilegios que permite la descarga en un archivo:

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

Privilegios de almacenamiento local

Este privilegio permite a un objeto visual personalizado almacenar información sobre el explorador local del usuario.

Este es un ejemplo de una configuración de privilegios que permite el uso del almacenamiento local:

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

No se necesitan privilegios

Si el objeto visual no requiere ningún permiso especial, la matriz privileges debe estar vacía:

  "privileges": []

Múltiples privilegios

En el ejemplo siguiente se muestra cómo establecer varios privilegios para un objeto visual personalizado.

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

dataroles: definición de los campos de datos que espera el objeto visual

Para definir los campos que se pueden enlazar con los datos, use dataRoles. dataRoles es una matriz de objetos DataViewRole que define todas las propiedades necesarias. Los objetos dataRoles son los campos que aparecen en el panel Propiedades.

El usuario arrastra campos de datos hasta ellos para enlazar los datos de los campos de datos a los objetos.

Propiedades de DataRole

Defina DataRoles con las siguientes propiedades:

• name: nombre interno de este campo de datos (tiene que ser único).
• displayName: nombre que se muestra al usuario en el panel Propiedades.
• kind: el tipo de campo:
  • Grouping: conjunto de valores discretos que se usan para agrupar campos de medida.
  • Measure: valores numéricos únicos.
  • GroupingOrMeasure: valores que se pueden usar como una agrupación o una medida.
• description: breve descripción textual del campo (opcional).
• requiredTypes: tipo de datos necesario para este rol de datos. Los valores que no coinciden se establecen en null (opcional).
• preferredTypes: tipo de datos preferido para este rol de datos (opcional).

Tipos de datos válidos para requiredTypes y preferredTypes

• bool: valor booleano.
• integer: valor entero.
• numeric: valor numérico.
• text: valor de texto.
• geography: datos geográficos.

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

Los roles de datos anteriores crearían los campos que se muestran en la siguiente imagen:

dataViewMappings: cómo quieren asignar los datos

Los objetos dataViewMappings describen cómo se relacionan los roles de datos entre sí y permiten especificar requisitos condicionales para mostrar vistas de datos.

La mayoría de los objetos visuales proporcionan una sola asignación, pero puede proporcionar varios elementos dataViewMappings. Cada asignación válida genera una vista de datos.

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

Para obtener más información, consulte Información sobre las asignaciones de vistas de datos en objetos visuales de Power BI.

objects: definen las opciones del panel de propiedades

Los objetos describen propiedades personalizables que están asociadas al objeto visual. Los objetos definidos en esta sección son los objetos que aparecen en el Panel de formato. Cada objeto puede tener varias propiedades y cada propiedad tiene un tipo asociado.

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

Por ejemplo, para admitir cadenas de formato dinámico en el objeto visual personalizado, defina el siguiente objeto:

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

Para obtener más información, vea Objetos y propiedades de objetos visuales de Power BI.

Contenido relacionado

• Información sobre las asignaciones de vistas de datos en objetos visuales de Power BI
• Objetos y propiedades de objetos visuales de Power BI
• Opciones de ordenación para objetos visuales de Power BI