Incorporare un report rapido in un'applicazione di analisi incorporata di Power BI per l'organizzazione

Le API client di Power BI consentono di creare rapidamente un report interattivo e un set di dati dai dati dell'applicazione senza che gli utenti debbano mai lasciare l'app. Usando questa libreria lato client, si forniranno informazioni sull'origine dati, che Power BI userà per generare un set di dati all'interno del servizio Power BI. Allo stesso tempo, Power BI genererà automaticamente un report con informazioni dettagliate sui dati che gli utenti possono esplorare e personalizzare per soddisfare le proprie esigenze.

In questa esercitazione si apprenderà come:

  • Configurare l'ambiente incorporato
  • Configurare un oggetto per archiviare informazioni sull'origine dati e personalizzare il report
  • Passare questo oggetto all'API per aggiungere funzionalità di esplorazione dei dati all'app

Per usare questa esperienza, gli utenti dovranno accedere a Power BI.

Si userà un oggetto di configurazione per archiviare informazioni sull'origine dati. Inoltre, è anche possibile usare l'oggetto di configurazione per personalizzare l'aspetto e il comportamento del report. Ad esempio, è possibile modificare il tema e le impostazioni di posizione nell'oggetto di configurazione. Quando si crea e si incorpora il set di dati, si passa l'oggetto all'API.

Importante

Se si incorpora contenuto per un cloud nazionale, i primi passaggi di questa esercitazione sono diversi. Per informazioni dettagliate, vedere Incorporare contenuto per i cloud nazionali.

Prerequisiti

Prima di iniziare questa esercitazione, verificare di avere entrambe le dipendenze di Power BI e del codice elencate di seguito:

  • Dipendenze di Power BI
  • Dipendenze del codice
    • Un editor di testo
    • Terminale della riga di comando, ad esempio PowerShell

Metodo

Le sezioni seguenti illustrano come incorporare e configurare il contenuto di Power BI usando l'editor di testo preferito.

L'interfaccia IQuickCreateConfiguration visualizza le proprietà che un oggetto di configurazione può fornire alle API client di Power BI relative al set di dati che si vuole creare:

Esempio

interface IQuickCreateConfiguration { 
    type?: "quickCreate"; 
    accessToken: string; 
    settings?: ISettings; 
    tokenType?: TokenType; 
    theme?: IReportTheme; 
    embedUrl?: string; 
    datasetCreateConfig: IDatasetCreateConfiguration; 
    reportCreationMode?: ReportCreationMode; 
    eventHooks?: EventHooks; 
}

Autorizzazione del token di accesso per QuickCreate

QuickCreate supporta solo i token AAD . Assicurarsi che l'applicazione abbia gli ambiti seguenti:

  • Content.Create
  • Dataset.ReadWrite.All
  • Report.Read.All
  • Workspace.Read.All

Per altre informazioni, vedere Registrare un'app per incorporare il contenuto di Power BI.

URL di incorporamento

Univoco per questa forma di incorporamento, questa esperienza ha una route speciale /quickcreate. Un url di incorporamento tipico per questa esperienza è simile al seguente: https://app.powerbi.com/quickcreate

Passaggio 1.1: Creare un set di dati senza un'origine dati

Power BI offre un modo semplice per consentire agli sviluppatori di includere i dati direttamente nella richiesta a Power BI se non è possibile configurare un'origine dati. La dimensione della richiesta viene limitata a 16 MB. Si noti che, poiché non esiste un'origine dati a cui Power BI si connette, non è possibile aggiornare il set di dati dopo la creazione.

  1. IDataTable

    IDataTable è essenzialmente un wrapper di una matrice di stringhe 2D in cui inserire i dati. Anche se i dati sono una matrice, per il momento è supportata solo una tabella dati. Il nome può essere impostato dall'utente, ma deve corrispondere al nome in ITableSchema.

    Per consentire a Power BI di analizzare i dati nel formato corretto, i valori dei dati devono essere formattati seguendo la specifica del valore del linguaggio M. La proprietà delle impostazioni locali definita in IQuickCreateConfiguration influisce anche sull'analisi dei valori. Per altre informazioni, vedere valori del linguaggio M - PowerQuery M.

    I dati devono essere passati in righe. Ogni riga deve contenere lo stesso numero di colonne definite in ITableSchema.  

    Nota

    I dati e tableSchemaList devono essere in coppia.

Esempio

const data: IDataTable = [
    { "name": "MyTableName", 
      "rows": [ 
              ["1", "1", "1991"], 
              ["1", "1", "1991"], 
        ]
    } 
]

Nota

Attualmente, la proprietà name non può essere personalizzata, quindi non è possibile assegnare un nome a una tabella. Il nome predefinito per la proprietà è "Table".

  1. ITableSchema

    Per comprendere i dati in Power BI, è necessario fornire lo schema per ogni colonna della tabella. Ogni schema di colonna deve avere un nome e un tipo. Il nome verrà usato come nome dell'elenco di campi dopo la creazione del set di dati. Il tipo è un subset della specifica del tipo di linguaggio M. I tipi supportati sono elencati facilmente in DataType. Per altre informazioni, vedere tipi di linguaggio M - PowerQuery M.

    Analogamente alla proprietà dei dati, anche se tableSchemaList è definita come matrice, per il momento è supportata solo una singola tabella.

    export const enum DataType { 
    Number = "Number", 
    Currency = "Currency", 
    Int32 = "Int32", 
    Percentage = "Percentage", 
    DateTime = "DateTime", 
    DateTimeZone = "DateTimeZone", 
    Date = "Date", 
    Time = "Time", 
    Duration = "Duration", 
    Text = "Text", 
    Logical = "Logical", 
    Binary = "Binary",  
    }

    Oltre al nome e al tipo di dati, gli utenti possono specificare l'aggregazione predefinita sulle colonne fornendo una proprietà facoltativa aggregateFunction per ogni colonna. Il numero per le funzioni di aggregazione supportate si basa sul tipo di enumerazione AggregateFunction.

Esempio

const tableSchemaList: ITableSchema = [{ 
    name: "MyTableName",  
    columns: [ 
        { 
            name: "createdby", 
            dataType: DataType.Text
             aggregateFunction: 6 // Count 
        }, 
        { 
            name: "createdon", 
            dataType: DataType.DateTime 
        }, 
        { 
            name: "size", 
            dataType: DataType.Number 
        } 
    ]     
}];   
const data: IDataTable = [
    { 
        "name": "MyTableName", 
        "rows": [ 
                ["1", "1", "1991"],
                ["1", "1", "1991"],
        ]
    }
] 
const datasetCreateConfig: IDatasetCreateConfiguration = {
    "modelName": "my model", 
    "locale": "en_US", 
    "tableSchemaList": tableSchemaList,
    "data": data
}

Passaggio 1.2: Creare un set di dati con l'origine dati esistente

IDatasetCreateConfiguration è una configurazione che consente a Power BI di sapere come creare il set di dati. Sono inclusi il documento Mashup, le impostazioni locali del set di dati e le informazioni di connessione che indicano a Power BI come connettersi all'origine dati.

Documento mashup

I documenti mashup o I documenti M dispongono di specifiche del linguaggio . Ai fini di questa esperienza di incorporamento, il modo più semplice per iniziare consiste nel connettersi all'origine dati preferita in Power BI Desktop e quindi copiare la query mashup risultante dalla visualizzazione dell'editor di query. Per informazioni dettagliate, vedere la documentazione dell'editor di query per Power BI Desktop.

Esempio

Let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeader(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

Per trasformare il codice sorgente precedente in un documento mashup, è sufficiente aggiungere una sezione . Una sezione include:

  • section-name;
  • shared section-member-name = expression;
  • dove expression sarà la query mashup,
  • e section-member-name verranno visualizzati in Power BI come nome di tabella/entità.

Per la query mashup di esempio fornita in precedenza, di seguito è riportato un esempio di documento mashup corrispondente:

"section Section1; shared #"Table" = let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

  Dopo aver creato il documento mashup, è possibile identificare quali parti saranno statiche e quali parti saranno dinamiche e possono essere compilate a livello di codice. Nell'esempio precedente sono presenti alcune variabili regolabili, il dominio del contenuto Web, il delimitatore, lo stile delle virgolette e se si desidera promuovere o meno le intestazioni. Di conseguenza, la query può essere trasformata in un modello e popolata con i parametri appropriati sul lato applicazione host, a seconda dei dati che l'utente sta consumando al momento.

Scena

Power BI userà le informazioni sulle impostazioni locali fornite in questa configurazione per valutare il documento mashup e analizzare i valori se vengono forniti dati non elaborati.

Configurazione dell'origine dati

Autorizzazione per l'origine dati

Attualmente è supportata solo la connessione anonima alle origini dati. Ciò significa che Power BI deve essere in grado di connettersi all'origine dati senza richiedere l'autenticazione.

Nota

Se si includono i dati direttamente nella richiesta, è necessario omettere la proprietà dataSourceConnection.

DataCacheMode

Per la maggior parte delle origini dati, modalità Importa deve soddisfare le proprie esigenze. Tuttavia, in alcuni casi in cui i dati cambiano rapidamente o quando le origini dati sono molto grandi, è anche possibile usare la modalità di DirectQuery. Se si ritiene che ciò possa essere applicabile, vedere altre informazioni su DirectQuery in Power BI.

Nota

Se si includono dati non elaborati nella richiesta, è necessario importare DataCacheMode.

Campione

const datasetCreateConfig: IDatasetCreateConfiguration = { 
    "modelName": "temp model", 
    "locale": "en_US", 
    "mashupDocument": "section Section1; shared Table = let Source = Csv.Document(Web.Contents(\"https://yourdomain.com/sample.csv\"),[Delimiter=\",\", QuoteStyle=QuoteStyle.None]), #\"Promoted Headers\" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #\"Promoted Headers\";", 
    "dataSourceConnection": { 
        "credentialType": CredentialType.Anonymous, // =1 
        "dataCacheMode": DataCacheMode.Import // =1 
    } 
}

Passaggio 2: Creare un set di dati e generare automaticamente un report

Ora con il set di datasetCreateConfig è possibile generare il set di dati e incorporare un report generato automaticamente. È simile al metodo createReport che consente di creare in incorporamento del report, il metodo quickCreate che accetta un contenitore iframe e il metodo quickCreateConfig che consente di incorporare il report.

Esempio

const powerbi = window.powerbi; 
const iframeContainer = document.getElementById("myIframeContainer"); 
const quickCreateConfig: IQuickCreateConfiguration = { 
    type: "quickCreate", 
    accessToken: "ey.....",  
    tokenType: TokenType.Aad, // Aad token only 
    embedUrl: "https://app.powerbi.com/quickcreate", // see below for generating the embed url 
    datasetCreateConfig: datasetCreateConfig, 
    reportCreationMode: ReportCreationMode.QuickExplore, // QuickExplore for auto-generated visual,    
    settings: { 
        localeSettings: { 
            language: "en_US" // this should match the current locale of your window/product. It will be used to localize the UI. 
        } 
    } 
}; 
const quickCreateReport = powerbi.quickCreate(iframeContainer, quickCreateConfig);

Contenuto correlato

  • Last updated on