Funcionalidades e propriedades de visuais do Power BI

Cada visual tem um arquivo capabilities.json que é criado automaticamente quando você executa o comando pbiviz new <visual project name> para criar um novo visual. O arquivo capabilities.json descreve o visual para o host.

O arquivo capabilities.json informa ao host que tipo de dados o visual aceita, quais atributos personalizáveis colocar no painel de propriedades e outras informações necessárias para criar o visual. A partir da API v4.6.0, todas as propriedades no modelo de recursos são opcionais, exceto privileges, que são necessárias.

O arquivo capabilities.json lista os objetos raiz no seguinte formato:

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

Quando você cria um visual, o arquivo capabilities.json padrão inclui os seguintes objetos raiz:

• privileges
• dataRoles
• dataViewMappings
• objects

Os objetos acima são aqueles necessários para a associação de dados. Eles podem ser editados conforme necessário para o seu visual.

Os outros objetos raiz a seguir são opcionais e podem ser adicionados conforme necessário:

• tooltips
• supportsHighlight
• classificação
• busca detalhada
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• subtotais
• keepAllMetadataColumns
• Migração

Você pode encontrar todos esses objetos e os respectivos parâmetros no esquema nocapabilities.json

privileges: define as permissões especiais que seu visual requer

Os privilégios são operações especiais às quais seu visual requer acesso para operar. Os privilégios recebem uma matriz de objetos privilege, que define todas as propriedades do privilégio. As seções a seguir descrevem os privilégios disponíveis no Power BI.

Observação

Na API v4.6.0, os privilégios devem ser especificados no arquivo capabilities.json. Em versões anteriores, o acesso remoto é concedido automaticamente e não é possível fazer download para arquivos. Para descobrir qual versão você está usando, confira apiVersion no arquivo pbiviz.json.

Definir privilégios

Uma definição de privilégio JSON contém estes componentes:

• name – (cadeia de caracteres) O nome do privilégio.
• essential – (booliano) Indica se a funcionalidade visual requer esse privilégio. Um valor de true significa que o privilégio é necessário; false significa que o privilégio não é obrigatório.
• parameters – (matriz de cadeia de caracteres)(opcional) Argumentos. Se parameters estiver ausente, será considerada uma matriz vazia.

A seguir, apresentamos os tipos de privilégios que devem ser definidos:

• Acesso a recursos externos
• Fazer download para arquivo
• Privilégios de armazenamento local

Observação

Mesmo com esses privilégios concedidos no visual, o administrador precisa habilitar a opção nas configurações de administrador para permitir que as pessoas em sua organização se beneficiem dessas configurações.

Permitir acesso à Web

Para que um visual possa acessar um recurso ou site externo, adicione essas informações como um privilégio na seção de capacidades. A definição de privilégio inclui uma lista opcional de URLs que o visual tem permissão para acessar no formato http://xyz.com ou https://xyz.com. Cada URL também pode incluir um curinga para especificar subdomínios.

O código a seguir é um exemplo de configuração de privilégios que permite acesso a recursos externos:

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

O privilégio anterior WebAccess significa que o visual precisa acessar qualquer subdomínio do domínio microsoft.com apenas por meio do protocolo HTTPS e example.com sem subdomínios via HTTP e que esse privilégio de acesso é essencial para que o visual funcione.

Fazer download para arquivo

Para permitir que o usuário exporte dados de um visual para um arquivo, defina ExportContent como true.

Essa configuração ExportContent permite que o visual exporte dados para arquivos nos seguintes formatos:

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

Essa configuração é separada e não é afetada pelas restrições de download aplicadas nas configurações de exportação e compartilhamento de locatário da organização.

O código a seguir é um exemplo de configuração de privilégios que permite fazer download para um arquivo:

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

Privilégios de armazenamento local

Esse privilégio permite que um visual personalizado armazene informações no navegador local do usuário.

Veja a seguir um exemplo de uma configuração de privilégios que permite o uso do armazenamento local:

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

Nenhum privilégio necessário

Se o visual não exigir permissões especiais, a matriz privileges deverá estar vazia:

  "privileges": []

Vários privilégios

O exemplo a seguir mostra como definir vários privilégios para um visual personalizado.

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

dataroles: definir os campos de dados esperados pelo visual

Para definir os campos que podem ser associados aos dados, use dataRoles. dataRoles é uma matriz de objetos DataViewRole, que define todas as propriedades necessárias. Os objetos dataRoles são os campos que aparecem no painel Propriedades.

O usuário arrasta os campos de dados até eles para associar os campos de dados aos objetos.

Propriedades de dataRole

Defina DataRoles com as seguintes propriedades:

• name: o nome interno deste campo de dados (deve ser exclusivo).
• displayName: o nome exibido para o usuário no painel Propriedades.
• tipo: o tipo de campo:
  • Grouping: Conjunto de valores discretos usados para agrupar campos de medida.
  • Measure: valores numéricos únicos.
  • GroupingOrMeasure: valores que podem ser usados como um agrupamento ou uma medida.
• description: um breve texto de descrição do campo (opcional).
• requiredTypes: o tipo de dados necessário para essa função de dados. Os valores que não correspondem são definidos como null (opcional).
• preferredTypes: o tipo de dados preferencial para essa função de dados (opcional).

Tipos de dados válidos para requiredTypes e preferredTypes

• bool: um valor booliano
• integer: um valor inteiro
• numeric: um valor numérico
• text: Um valor de texto
• geography: um dado geográfico

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

As funções de dados anteriores criariam os campos exibidos na imagem a seguir:

dataViewMappings: como você deseja mapear os dados

Os objetos dataViewMappings descrevem como as funções de dados se relacionam entre si e permitem que você especifique requisitos condicionais para as exibições de dados.

A maioria dos visuais fornece um mapeamento único, mas você pode fornecer vários DataViewMappings. Cada mapeamento válido produz uma exibição de dados.

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

Para obter mais informações, confira Entender o mapeamento de exibição de dados em visuais do Power BI.

objects: definir opções do painel de propriedade

Objetos descrevem propriedades personalizáveis associadas ao visual. Os objetos definidos nesta seção são os objetos que aparecem no painel Formatar. Cada objeto pode ter múltiplas propriedades e cada propriedade possui um tipo associado a ela.

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

Por exemplo, para oferecer suporte a cadeias de caracteres de formato dinâmico em seu visual personalizado, defina o seguinte objeto:

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

Para obter mais informações, confira Objetos e propriedades de visuais do Power BI.

Conteúdo relacionado

• Entender o mapeamento de exibição de dados em visuais do Power BI
• Objetos e propriedades de visuais do Power BI
• Opções de classificação para visuais do Power BI