Introdução

7 minutos

Para incorporar conteúdos do Power BI na sua aplicação, tem de concluir as seguintes tarefas de desenvolvimento.

Adicione a biblioteca de cliente para controlar programaticamente a incorporação.
Inclua a biblioteca de cliente.
Adicione um contentor de incorporação.
Factos gerados do lado do servidor de saída.
Configurar um objeto de configuração.
Incorpore o conteúdo do Power BI.

Adicionar a biblioteca de cliente

Utilize a API de cliente do Power BI para incorporar conteúdo do Power BI com JavaScript ou TypeScript. É uma biblioteca de cliente que fornece controlo programático de toda a experiência de incorporação.

As APIs incluem três pacotes:

powerbi-client - Inclui todas as APIs que incorporaram conteúdo, exceto as APIs encontradas na biblioteca de criação de relatórios powerbi .
powerbi-models - Contém modelos de objetos. Cada modelo tem uma interface TypeScript, uma definição de esquema JSON e uma função de validação para garantir que um determinado objeto é um modelo válido.
powerbi-report-authoring – uma extensão para criar e personalizar elementos visuais e criar um relatório do Power BI depois de ser carregado. Também permite que a sua aplicação edite programaticamente relatórios incorporados do Power BI.

Pode instalar a biblioteca de API de cliente do Power BI com o NuGet ou npm.

Para obter mais informações, consulte O que é a API de Cliente de Análise incorporada do Power BI?.

Incluir a biblioteca de cliente

A sua aplicação tem de incluir um script elemento para obter a biblioteca de cliente.

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

Também é possível obter a biblioteca de cliente a partir de uma rede de entrega de conteúdos (CDN). Por exemplo, veja JSDelivr powerbi-client.

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

Quando incluída diretamente, a biblioteca de cliente é exposta como um powerbi-client global chamado. Há também outro powerbi global chamado, que é uma instância do serviço Power BI.

Adicionar um contentor de incorporação

A aplicação tem de incluir um div elemento que aja como o contentor de incorporação.

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

A aplicação incorpora conteúdo do Power BI no elemento, alojando div o conteúdo dentro de um iframe elemento. O iframe elemento cria uma separação entre a aplicação e o conteúdo incorporado, certificando-se de que os dados são seguros. As APIs cliente comunicam sempre de forma segura entre a aplicação e o conteúdo incorporado.

Veja o seguinte vídeo que demonstra como funciona a biblioteca de cliente.

Factos gerados do lado do servidor de saída

A sua aplicação tem de adquirir um token de acesso do lado do cliente de saída. Além disso, a aplicação tem de produzir determinadas propriedades do artefacto do Power BI do lado do cliente.

Dica

Para saber como adquirir tokens de acesso e obter propriedades de artefactos do Power BI, trabalhe através do módulo Configurar permissões para incorporar conteúdo do Power BI .

O elemento seguinte script contém três variáveis. A accessToken variável armazena o token de acesso gerado do lado do servidor. As reports variáveis e datatsets armazenam representações JSON de artefactos incorporados. Neste exemplo, os tipos de artefactos são relatórios e conjuntos de dados. Especificamente, as variáveis armazenam o ID do artefacto e incorporam propriedades de URL que têm de estar disponíveis do lado do cliente para suportar a incorporação. Também inclui a propriedade name para que a aplicação possa apresentar nomes de artefactos ao utilizador de uma forma amigável, como num menu.

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

Configurar um objeto de configuração

A sua aplicação tem de criar um objeto de configuração para fornecer todas as informações necessárias para incorporar conteúdo do Power BI. Tem de definir as seguintes cinco propriedades do objeto de configuração:

tokenType - Defina o valor com base num destes cenários:
- Para a sua organização O token de acesso é um token de Azure AD. Defina o valor como models.TokenType.Aad.
- Para os seus clientes O token de acesso é um token de incorporação. Defina o valor como models.TokenType.Embed.
accessToken - O token de acesso gerado do lado do servidor.
type - Defina para um dos seguintes valores. As unidades 2 e 3 descrevem como incorporar cada tipo de conteúdo do Power BI.
- relatório Para um relatório do Power BI ou relatório paginado.
- elemento visual Para um elemento visual de relatório do Power BI.
- dashboard Para um dashboard.
- mosaico Para um mosaico de dashboard.
- qna Para a experiência Q&A.
id - O ID do artefacto do Power BI.
embedUrl - O URL de incorporação do artefacto do Power BI. Este URL torna-se a origem do iframe elemento que aloja o artefacto incorporado. Especificamente, a API atribui o URL ao src atributo do iframe elemento.

O código seguinte mostra como criar um objeto de configuração para incorporar um relatório do Power BI com o cenário Para os seus clientes . models é uma referência aos modelos de biblioteca de cliente, que contêm tipos de enumeração úteis (enums).

// 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>'
};

Existem mais propriedades de configuração específicas do conteúdo que pode definir. São descritos nas unidades 2 e 3.

Incorporar o conteúdo do Power BI

Utilize a powerbi.embed(embedContainer, config) função para incorporar o conteúdo do Power BI.

O código seguinte mostra como incorporar um relatório do Power BI. A embedContainer variável armazena uma referência ao contentor de incorporação (div elemento), enquanto a config variável armazena o objeto de configuração configurado para um relatório específico do Power BI. A última instrução faz a incorporação ao transmitir o contentor de incorporação e o objeto de configuração. A report variável armazena uma referência ao relatório incorporado.

// 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);

Na unidade seguinte, irá aprender a incorporar um relatório do Power BI, que é o tipo de conteúdo do Power BI mais frequentemente incorporado.

Continuar