Introduzione

7 minuti

Per incorporare il contenuto di Power BI in un'app, è necessario completare le attività di sviluppo seguenti.

Aggiungere la libreria client per controllare a livello di codice l'incorporamento.
Includere la libreria client.
Aggiungere un contenitore di incorporamento.
Restituire fact generati sul lato server.
Configurare un oggetto di configurazione.
Incorporare il contenuto di Power BI.

Aggiungere la libreria client

Usare l'API client di Power BI per incorporare il contenuto di Power BI usando JavaScript o TypeScript. Si tratta di una libreria client che fornisce il controllo programmatico dell'intera esperienza di incorporamento.

Le API comprendono tre pacchetti:

powerbi-client : include tutte le API che incorporano il contenuto, ad eccezione delle API disponibili nella libreria powerbi-report-authoring .
powerbi-models: contiene modelli a oggetti. Ogni modello ha un'interfaccia TypeScript, una definizione di schema JSON e una funzione di convalida per garantire che un determinato oggetto sia un modello valido.
powerbi-report-authoring: un'estensione per la creazione e la personalizzazione degli oggetti visivi e la creazione di un report di Power BI dopo il caricamento. Consente anche all'app di modificare a livello di codice i report di Power BI incorporati.

È possibile installare la libreria di API client di Power BI usando NuGet o npm.

Per altre informazioni, vedere Che cos'è l'API client di analisi incorporata di Power BI?

Includere la libreria client

L'app deve includere un elemento script per acquisire la libreria client.

<script src="/powerbi-client/dist/powerbi.js"></script>

È anche possibile acquisire la libreria client da una rete per la distribuzione di contenuti (rete CDN). Per un esempio, vedere JSDelivr powerbi-client.

<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.22.3/dist/powerbi.min.js"></script>

Se inclusa direttamente, la libreria client viene esposta come oggetto globale denominato powerbi-client. È presente anche un altro oggetto globale denominato powerbi, ovvero un'istanza del servizio Power BI.

Aggiungere un contenitore di incorporamento

L'app deve includere un elemento div che funge da contenitore di incorporamento.

<div id="embedContainer"></div>

L'app incorpora il contenuto di Power BI nell'elemento div, ospitando il contenuto all'interno di un elemento iframe. L'elemento iframe crea una separazione tra l'app e il contenuto incorporato, assicurandosi che i dati siano sicuri. Le comunicazioni delle API client tra l'app e il contenuto incorporato sono sempre sicure.

Guardare il video seguente che illustra il funzionamento della libreria client.

Restituire fact generati sul lato server

L'app deve acquisire un token di accesso che viene restituito sul lato client. Inoltre, l'app deve restituire determinate proprietà degli artefatti di Power BI sul lato client.

Suggerimento

Per informazioni su come acquisire i token di accesso e recuperare le proprietà degli artefatti di Power BI, usare il modulo Configurare le autorizzazioni per incorporare contenuto di Power BI.

L'elemento script seguente contiene tre variabili. La variabile accessToken archivia il token di accesso generato sul lato server. Le variabili reports e datatsets archiviano le rappresentazioni JSON degli artefatti incorporabili. In questo esempio i tipi di artefatto sono report e set di dati. In particolare, le variabili archiviano l'ID artefatto e incorporano le proprietà dell'URL che devono essere disponibili sul lato client per supportare l'incorporamento. Include anche la proprietà name in modo che l'app possa presentare i nomi degli artefatti all'utente in modo descrittivo, come in un menu.

<script>
    var accessToken = "@Model.AccessToken";
    var reports = @Html.Raw(Model.ReportsJson)
    var datasets = @Html.Raw(Model.DatasetsJson)
</script>

Configurare un oggetto di configurazione

L'app deve creare un oggetto di configurazione per fornire tutte le informazioni necessarie per incorporare il contenuto di Power BI. È necessario impostare le cinque proprietà seguenti dell'oggetto di configurazione:

tokenType - Impostare il valore in base a uno di questi scenari:
- Per l'organizzazione Il token di accesso è un token di Azure AD. Impostare il valore su models.TokenType.Aad.
- Per i clienti Il token di accesso è un token di incorporamento. Impostare il valore su models.TokenType.Embed.
accessToken: token di accesso generato sul lato server.
type - Impostare su uno dei valori seguenti. Le unità 2 e 3 descrivono come incorporare ogni tipo di contenuto di Power BI.
- Report Per un report di Power BI o un report impaginato.
- Visual Per un oggetto visivo report di Power BI.
- cruscotto Per un dashboard.
- Piastrelle Per un riquadro del dashboard.
- qna Per l'esperienza Q&A.
id: ID artefatto di Power BI.
embedUrl: URL di incorporamento dell'artefatto di Power BI. Questo URL diventa l'origine dell'elemento iframe che ospita l'artefatto incorporato. In particolare, l'API assegna l'URL all'attributo src dell'elemento iframe.

Il codice seguente illustra come creare un oggetto di configurazione per incorporare un report di Power BI usando lo scenario Per i clienti. models è un riferimento ai modelli della libreria client, che contengono tipi di enumerazione utili (enumerazioni).

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

Sono disponibili altre proprietà di configurazione specifiche del contenuto che è possibile impostare. Sono descritte nelle unità 2 e 3.

Incorporare il contenuto di Power BI

Usare la funzione powerbi.embed(embedContainer, config) per incorporare il contenuto di Power BI.

Il codice seguente illustra come incorporare un report di Power BI. La variabile embedContainer archivia un riferimento al contenitore di incorporamento (elemento div), mentre la variabile config archivia l'oggetto di configurazione configurato per un report di Power BI specifico. L'ultima istruzione esegue l'incorporamento passando il contenitore di incorporamento e l'oggetto di configurazione. La variabile report archivia un riferimento al report incorporato.

// Get models. models contains enums that can be used.
models = window['powerbi-client'].models;

// Get a reference to the embedding container.
let embedContainer = $('#embedContainer')[0];

// Create the embed configuration object.
let config = {
    tokenType: models.TokenType.Embed,
    accessToken: accessToken, // Server-side generated access token
    type: 'report',
    id: '<Server-side retrieved Report ID>',
    embedUrl: '<Server-side retrieved Report embed URL>'
};

// Embed the report in the embedding container.
report = powerbi.embed(embedContainer, config);

Nell'unità successiva si apprenderà come incorporare un report di Power BI, che è il tipo di contenuto di Power BI più comunemente incorporato.

Continua