Funzionalità e proprietà degli oggetti visivi di Power BI

  • Articolo

Ogni oggetto visivo ha un file capabilities.json creato automaticamente quando si esegue il pbiviz new <visual project name> comando 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 privilegesdi , 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:

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

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

È 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 privilege oggetti, 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 il file di pbiviz.json .

Definire i privilegi

Una definizione di privilegio JSON contiene questi componenti:

  • name - (stringa) Nome del privilegio.
  • essential - (Boolean) Indica se la funzionalità visiva richiede questo privilegio. Un valore indica true 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:

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.

Consenti 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 capabilities. 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.

Di seguito è riportato 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 precedente WebAccess indica che l'oggetto visivo deve accedere a qualsiasi sottodominio del microsoft.com dominio solo tramite protocollo HTTPS e example.com senza sottodomini tramite HTTP e che questo privilegio di accesso è essenziale per il funzionamento dell'oggetto visivo.

Scarica nel file

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

Questa ExportContent impostazione 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.

Di seguito è riportato 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 privileges matrice 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, usare dataRoles. dataRoles è una matrice di DataViewRole oggetti, che definisce tutte le proprietà necessarie. Gli dataRoles oggetti sono i campi visualizzati nel riquadro Proprietà.

L'utente trascina i campi dati in tali campi per associare i dati ai campi dati agli oggetti .

Proprietà DataRole

DataRoles sono definiti dalle proprietà seguenti:

  • name: nome interno di questo campo dati (deve essere univoco).
  • displayName: nome visualizzato all'utente nel riquadro Proprietà .
  • kind: Tipo di campo:
    • Grouping: set di valori discreti utilizzati 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 (facoltativo).
  • preferredTypes: tipo di dati preferito per questo ruolo dati (facoltativo).

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

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

Data role fields

dataViewMappings: modalità di mapping dei dati

Gli dataViewMappings oggetti 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 singolo mapping, ma è possibile fornire più oggetti dataViewMappings. Ogni mapping valido produce una visualizzazione dati.

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

Per altre informazioni, vedere Informazioni sul mapping delle visualizzazioni dati negli 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. A ogni oggetto possono essere associate 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à degli oggetti visivi di Power BI.

Contenuto correlato