Funzionalità e proprietà degli oggetti visivi di Power BI

Per ogni oggetto visivo è creato automaticamente un file capabilities.json quando si esegue il comando pbiviz new <visual project name> per creare un nuovo oggetto visivo. Il file capabilities.json descrive l'oggetto visivo dell'host.

Il file capabilities.json indica all'host quale tipo di dati accetta l'oggetto visivo, quali attributi personalizzabili inserire nel riquadro delle proprietà e altre informazioni necessarie per creare l'oggetto visivo. A partire dall'API v4.6.0, tutte le proprietà del modello di funzionalità sono facoltative ad eccezione di privileges, che sono obbligatorie.

Il file capabilities.json elenca gli oggetti radice nel formato seguente:

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

Quando si crea un nuovo oggetto visivo, il file di capabilities.json predefinito include gli oggetti radice seguenti:

• privileges
• dataRoles
• dataViewMappings
• objects

Gli oggetti precedenti sono quelli necessari per il data binding. Possono essere modificati in base alle esigenze dell'oggetto visivo.

Gli altri oggetti radice seguenti sono facoltativi e possono essere aggiunti in base alle esigenze:

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

È possibile trovare tutti questi oggetti e i relativi parametri nello schema capabilities.json

privilegi: definire le autorizzazioni speciali richieste dall'oggetto visivo

I privilegi sono operazioni speciali a cui l'oggetto visivo richiede l'accesso per funzionare. I privilegi accettano una matrice di oggetti privilege, che definisce tutte le proprietà dei privilegi. Le sezioni seguenti descrivono i privilegi disponibili in Power BI.

Nota

Dall'API v4.6.0, i privilegi devono essere specificati nel file capabilities.json. Nelle versioni precedenti, l'accesso remoto viene concesso automaticamente e il download ai file non è possibile. Per scoprire quale versione si sta usando, archiviare apiVersion nel file pbiviz.json.

Definire i privilegi

Una definizione di privilegio JSON contiene questi componenti:

• name - (stringa) Nome del privilegio.
• essential - (Booleano) Indica se la funzionalità visiva richiede questo privilegio. Un valore true indica che il privilegio è obbligatorio; false significa che il privilegio non è obbligatorio.
• parameters - (matrice di stringhe)(facoltativo) Argomenti. Se parameters manca, viene considerata una matrice vuota.

Di seguito sono riportati i tipi di privilegi che devono essere definiti:

• Accedere alle risorse esterne
• Scaricare in un file
• Privilegi di archiviazione locale

Nota

Anche con questi privilegi concessi nell'oggetto visivo, l'amministratore deve abilitare l'opzione nelle impostazioni di amministrazione per consentire agli utenti dell'organizzazione di trarre vantaggio da queste impostazioni.

Consentire l'accesso Web

Per consentire a un oggetto visivo di accedere a una risorsa esterna o a un sito Web, aggiungere tali informazioni come privilegio nella sezione delle capacità. La definizione dei privilegi include un elenco facoltativo di URL a cui l'oggetto visivo può accedere nel formato http://xyz.com o https://xyz.com. Ogni URL può includere anche un carattere jolly per specificare i sottodomini.

Il codice seguente è un esempio di impostazione dei privilegi che consente l'accesso alle risorse esterne:

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

Il privilegio WebAccess precedente indica che l'oggetto visivo deve accedere a qualsiasi sottodominio del dominio microsoft.com solo tramite protocollo HTTPS e example.com senza sottodomini tramite HTTP e che questo privilegio di accesso è essenziale per il funzionamento dell'oggetto visivo.

Scaricare in un file

Per consentire all'utente di esportare i dati da un oggetto visivo in un file, impostare ExportContent su true.

Questa impostazione ExportContent consente all'oggetto visivo di esportare i dati nei file nei formati seguenti:

• .txt
• .csv
• .json
• TMPLT
• .xml
• PDF
• XLSX

Questa impostazione è separata da e non è interessata dalle restrizioni di download applicate nelle impostazioni del tenant di esportazione e condivisione dell'organizzazione.

Il codice seguente è un esempio di impostazione dei privilegi che consente il download in un file:

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

Privilegi di archiviazione locale

Questo privilegio consente a un oggetto visivo personalizzato di archiviare informazioni nel browser locale dell'utente.

Di seguito è riportato un esempio di impostazione dei privilegi che consente l'uso dell'archiviazione locale:

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

Nessun privilegio necessario

Se l'oggetto visivo non richiede autorizzazioni speciali, la matrice privileges deve essere vuota:

  "privileges": []

Più privilegi

Nell'esempio seguente viene illustrato come impostare diversi privilegi per un oggetto visivo personalizzato.

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

dataroles: definire i campi dati previsti dall'oggetto visivo

Per definire i campi che possono essere associati ai dati, si usa dataRoles. dataRoles è una matrice di oggetti DataViewRole, che definisce tutte le proprietà obbligatorie. Gli oggetti dataRoles sono i campi visualizzati nel riquadro Proprietà.

L'utente trascina qui i campi dati per associarli agli oggetti.

Proprietà DataRole

Definire DataRole con le proprietà seguenti:

• name: nome interno di questo campo dati (deve essere univoco).
• displayName: nome visualizzato all'utente nel riquadro delle Proprietà.
• kind: tipo di campo:
  • Grouping: set di valori discreti usati per raggruppare i campi delle misure.
  • Measure: valori numerici singoli.
  • GroupingOrMeasure: valori che possono essere usati come raggruppamento o misura.
• description: breve descrizione del campo (facoltativo).
• requiredTypes: tipo di dati richiesto per questo ruolo dati. I valori che non corrispondono sono impostati su null (proprietà facoltativa).
• preferredTypes: tipo di dati preferito per questo ruolo dati (proprietà facoltativa).

Tipi di dati validi per requiredTypes e preferredTypes

• bool: valore booleano
• integer: valore intero
• numeric: valore numerico
• text: valore di testo
• geography: dati geografici

Esempio di dataRole

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

I ruoli dei dati precedenti creeranno i campi visualizzati nell'immagine seguente:

dataViewMapping: modalità di mapping dei dati

Gli oggetti dataViewMappings descrivono il modo in cui i ruoli dati sono correlati tra loro e consentono di specificare i requisiti condizionali per la visualizzazione delle viste dati.

La maggior parte degli oggetti visivi fornisce un solo mapping, ma è possibile fornire più oggetti dataViewMapping. Ogni mapping valido genera una visualizzazione dati.

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

Per altre informazioni, vedere Mapping di viste dati in oggetti visivi di Power BI.

oggetti: definire le opzioni del riquadro delle proprietà

Gli oggetti descrivono proprietà personalizzabili associate all'oggetto visivo. Gli oggetti definiti in questa sezione sono gli oggetti visualizzati nel riquadro Formato. Ogni oggetto può avere più proprietà e a ogni proprietà è associato un tipo.

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

Ad esempio, per supportare stringhe di formato dinamico nell'oggetto visivo personalizzato, definire l'oggetto seguente:

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

Per altre informazioni, vedere Oggetti e proprietà.

Contenuto correlato

• Informazioni sul mapping di viste dati in oggetti visivi di Power BI
• Oggetti e proprietà degli oggetti visivi di Power BI
• Opzioni di ordinamento per gli oggetti visivi di Power BI