Tutorial: Inserir relatórios paginados do Power BI em um aplicativo para seus clientesTutorial: Embed Power BI paginated reports into an application for your customers

Com o Power BI Embedded no Azure ou a Inserção do Power BI no Office, você pode inserir relatórios paginados em um aplicativo usando app owns data.With Power BI Embedded in Azure or Power BI embedding in Office, you can embed paginated reports into an application using app owns data. App owns data representa um aplicativo que usa o Power BI como sua plataforma de análise incorporada.App owns data is about having an application that uses Power BI as its embedded analytics platform. Como um ISV ou um desenvolvedor, é possível criar conteúdo do Power BI que exiba relatórios paginados em um aplicativo totalmente integrado e interativo, sem precisar que os usuários tenham uma licença do Power BI.As an ISV or a developer, you can create Power BI content that displays paginated reports in an application that is fully integrated and interactive, without requiring users to have a Power BI license. Este tutorial demonstra como integrar um relatório paginado em um aplicativo usando o SDK do .NET do Power BI com as APIs do Cliente do Power BI.This tutorial demonstrates how to integrate a paginated report into an application using the Power BI .NET SDK with the Power BI Client APIs.

Relatório de Inserção do Power BI

Neste tutorial, você aprenderá a:In this tutorial, you learn how to:

  • Registrar um aplicativo no Azure.Register an application in Azure.
  • Insira um relatório paginado do Power BI em um aplicativo.Embed a Power BI paginated report into an application.

Pré-requisitosPrerequisites

Para começar, você precisa ter:To get started, you're required to have:

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Importante

Configurar seu ambiente do Power BISet up your Power BI environment

A inserção de um relatório paginado requer a atribuição de um workspace a uma capacidade e o carregamento do relatório no workspace.Embedding a paginated report requires assigning a workspace to a capacity, and uploading the report to the workspace.

Criar um workspace de aplicativoCreate an app workspace

Uma vez que você está usando uma entidade de serviço para entrar em seu aplicativo, é necessário usar os novos workspaces.As you're using a service principal to sign into your application, you're required to use the new workspaces. Como uma entidade de serviço, você também deve ser um administrador ou membro dos workspaces do aplicativo envolvidos em seu aplicativo.As a service principal, you must also be an admin or member of the app workspaces involved with your application.

Criar uma capacidadeCreate a capacity

Antes de importar ou carregar um relatório paginado para inserir, o workspace que contém o relatório deve ser atribuído a pelo menos uma capacidade A4 ou P1.Before you import or upload a paginated report to embed, the workspace containing the report must be assigned to at least an A4 or P1 capacity. Há dois tipos de capacidade dentre as quais você pode escolher:There are two types of capacity you can choose from:

  • Power BI Premium – para inserir um relatório paginado, é necessário ter uma capacidade P SKU.Power BI Premium - For embedding a paginated report, a P SKU capacity is required. Ao inserir conteúdo do Power BI, essa solução é conhecida como inserção do Power BI.When embedding Power BI content, this solution is referred to as Power BI embedding. Para obter mais informação sobre essa assinatura, consulte o que é Power BI Premium?For more information regarding this subscription, see What is Power BI Premium?

  • Azure Power BI Embedded – para comprar uma capacidade, acesse o portal do Microsoft Azure.Azure Power BI Embedded - You can purchase a capacity from the Microsoft Azure portal. Essa assinatura usa os SKUs A.This subscription uses the A SKUs. Para inserir relatórios paginados, você precisa de pelo menos uma assinatura A4.For embedding paginated reports you need at least an A4 subscription. Para obter detalhes sobre como criar uma capacidade do Power BI Embedded, veja Criar capacidade do Power BI Embedded no portal do Azure.For details on how to create a Power BI Embedded capacity, see Create Power BI Embedded capacity in the Azure portal.

    Observação

    O Power BI Embedded lançou recentemente uma nova versão, chamada de Embedded Gen2.Power BI Embedded recently released a new version, called Embedded Gen2. A Embedded Gen2 vai simplificar o gerenciamento de capacidades inseridas e aprimorar a experiência do Power BI Embedded.Embedded Gen2 will simplify the management of embedded capacities, and improve the Power BI Embedded experience. Para obter mais informações, confira Power BI Embedded Geração 2.For more information, see Power BI Embedded Generation 2.

A tabela a seguir descreve os recursos e limites de cada SKU.The table below describes the resources and limits of each SKU. Para determinar qual capacidade atende melhor às suas necessidades, consulte a tabela Qual SKU devo comprar para meu cenário.To determine which capacity best fits your needs, see the which SKU should I purchase for my scenario table.

Nós de CapacidadeCapacity Nodes Total de núcleos virtuaisTotal v-cores Núcleos virtuais de back-endBackend v-cores RAM (GB)RAM (GB) Núcleos virtuais de front-endFrontend v-cores
A1 com Embedded Gen2A1 with Embedded Gen2 11 0,50.5 2.52.5 0,50.5
A2 com Embedded Gen2A2 with Embedded Gen2 22 11 55 11
A3 com Embedded Gen2A3 with Embedded Gen2 44 22 1010 22
P1/A4P1/A4 88 44 2525 44
P2/A5P2/A5 1616 88 5050 88
P3/A6P3/A6 3232 1616 100100 1616

Atribuir um workspace de aplicativo a uma capacidadeAssign an app workspace to a capacity

Depois de criar uma capacidade, você pode atribuir o workspace do aplicativo a uma capacidade.Once you create a capacity, you can assign your app workspace to that capacity.

Para atribuir uma capacidade a um workspace usando entidade de serviço, use a API REST do Power BI.To assign a capacity to a workspace using service principal, use the Power BI REST API. Quando você estiver usando as APIs REST do Power BI, use a ID de objeto de entidade de serviço.When you are using the Power BI REST APIs, make sure to use the service principal object ID.

Criar e carregar relatórios paginadosCreate and upload your paginated reports

Você pode criar seu relatório paginado usando o Construtor de Relatórios do Power BI e, em seguida, carregar o relatório no serviço.You can create your paginated report using Power BI Report Builder, and then upload the report to the service.

Você pode importar relatórios paginados para os novos workspaces usando as APIs REST do Power BI.You can import paginated reports into the new workspaces using the Power BI REST APIs.

Insira conteúdo usando o aplicativo de exemploEmbed content using the sample application

Este exemplo é deliberadamente mantido simples para fins de demonstração.This sample is deliberately kept simple for demonstration purposes. Cabe a você ou a seus desenvolvedores proteger o segredo do aplicativo.It's up to you or your developers to protect the application secret.

Siga as etapas abaixo para começar a inserir seu conteúdo usando o aplicativo de exemplo.Follow the steps below to start embedding your content using the sample application.

  1. Baixe o Visual Studio (versão 2013 ou posterior).Download Visual Studio (version 2013 or later). Baixe a versão mais recente do pacote do NuGet.Make sure to download the latest NuGet package.

  2. Baixe o exemplo App Owns Data do GitHub para começar.Download the App Owns Data sample from GitHub to get started.

    Exemplo de aplicativo App Owns Data

  3. Abra o arquivo Web.config no aplicativo de exemplo.Open the Web.config file in the sample application. Há campos que você precisa preencher para executar o aplicativo.There are fields you need to fill in to run the application. Escolha ServicePrincipal para o AuthenticationType.Choose ServicePrincipal for the AuthenticationType.

    Preencha os campos a seguir:Fill in the following fields:

    Observação

    O padrão AuthenticationType neste exemplo é MasterUser.The default AuthenticationType in this sample is MasterUser. Altere-o para ServicePrincipal.Make sure you change it to ServicePrincipal.

    Arquivo de configuração da Web

ID do aplicativoApplication ID

Preencha as informações de applicationId com a ID do Aplicativo do Azure.Fill in the applicationId information with the Application ID from Azure. A applicationId é usada pelo aplicativo para identificar-se aos usuários para os quais você está solicitando permissões.The applicationId is used by the application to identify itself to the users from which you're requesting permissions.

Para obter a applicationId, siga estas etapas:To get the applicationId, follow these steps:

  1. Entre no Portal do Azure.Sign into the Azure portal.

  2. No painel de navegação esquerdo, escolha Todos os serviços e pesquise Registros de Aplicativo.In the left-hand nav pane, select All Services, and search for App Registrations.

    Pesquisa de registro de aplicativo

  3. Selecione o aplicativo que precisa usar a applicationId.Select the application that needs the applicationId.

    A captura de tela mostra os nomes de exibição dos aplicativos. O nome selecionado precisa da ID do aplicativo.

  4. Há uma ID do Aplicativo listada como GUID.There's an Application ID that is listed as a GUID. Use essa ID do aplicativo como a applicationId do aplicativo.Use this Application ID as the applicationId for the application.

    applicationId

ID do workspaceWorkspace ID

Preencha as informações de workspaceId com o GUID do workspace (grupo) do aplicativo do Power BI.Fill in the workspaceId information with the app workspace (group) GUID from Power BI. Você pode obter essas informações da URL, quando estiver conectado ao serviço do Power BI ou quando estiver usando o PowerShell.You can get this information either from the URL when signed into the Power BI service or using PowerShell.

URLURL

workspaceId

PowerShellPowerShell

Get-PowerBIworkspace -name "Paginated Report Embed"

workspaceId do PowerShell

ID do RelatórioReport ID

Preencha as informações de reportId com o GUID de relatório do Power BI.Fill in the reportId information with the report GUID from Power BI. Você pode obter essas informações da URL, quando estiver conectado ao serviço do Power BI ou quando estiver usando o PowerShell.You can get this information either from the URL when signed into the Power BI service or using PowerShell.

URLURL

reportId

PowerShellPowerShell

Get-PowerBIworkspace -name "Paginated Report Embed" | Get-PowerBIReport

reportId do PowerShell

Segredo do aplicativoApplication secret

Preencha as informações de ApplicationSecret da seção Chaves na seção Registros de aplicativo no Azure.Fill in the ApplicationSecret information from the Keys section of your App registrations section in Azure.

Para obter o ApplicationSecret, siga estas etapas:To get the ApplicationSecret, follow these steps:

  1. Entre no portal do Azure.Sign in to the Azure portal.

  2. No painel de navegação esquerdo, selecione Todos os serviços e pesquise Registros de aplicativo.In the left-hand nav pane, select All services and search for App registrations.

    Pesquisa de registro de aplicativo

  3. Selecione o aplicativo que precisa usar o ApplicationSecret.Select the application that needs to use the ApplicationSecret.

    A captura de tela mostra os nomes de exibição dos aplicativos. O nome selecionado precisa do segredo do aplicativo.

  4. Selecione Certificados e segredos em Gerenciar.Select Certificates and secrets under Manage.

  5. Selecione Segredos do novo cliente.Select New client secrets.

  6. Insira um nome na caixa Descrição e selecione uma duração.Enter a name in the Description box and select a duration. Em seguida, selecione Salvar para obter o Valor para seu aplicativo.Then select Save to get the Value for your application. Quando você fecha o painel Chaves depois de salvar o valor da chave, o campo de valor é mostrado como oculto.When you close the Keys pane after saving the key value, the value field shows only as hidden. Neste ponto, você não pode recuperar o valor da chave.At that point, you aren't able to retrieve the key value. Se você perder o valor da chave, crie uma nova no portal do Azure.If you lose the key value, create a new one in the Azure portal.

    Valor da chave

LocatárioTenant

Preencha as informações do locatário com a sua ID de locatário do Azure.Fill in the tenant information with your Azure tenant ID. Essas informações estão disponíveis no Centro de administração do Microsoft Azure AD, quando você está conectado ao serviço do Power BI ou quando está usando o PowerShell.You can get this information from the Azure AD admin center when signed into the Power BI service or by using PowerShell.

Execute o aplicativoRun the application

  1. Selecione Executar no Visual Studio.Select Run in Visual Studio.

    Execute o aplicativo

  2. Selecione Inserir Relatório.Then select Embed Report.

    Selecione um conteúdo

  3. Agora, você pode exibir o relatório no aplicativo de exemplo.Now you can view the report in the sample application.

    Exibir o aplicativo

Inserir relatórios paginados do Power BI em seu aplicativoEmbed Power BI paginated reports within your application

Embora as etapas para inserir seus relatórios paginados do Power BI sejam feitas com as APIs REST do Power BI, os códigos de exemplo descritos neste artigo são feitos com o SDK do .NET.Even though the steps to embed your Power BI paginated reports are done with the Power BI REST APIs, the example codes described in this article are made with the .NET SDK.

A inserção dos relatórios paginados do Power BI para seus clientes em seu aplicativo exige que você tenha uma entidade de serviço do Azure AD e obtenha um token de acesso do Azure AD para seu aplicativo Power BI antes de fazer chamadas para as APIs REST do Power BI.Embedding Power BI paginated reports for your customers within your application, requires you to have an Azure AD service principal and get an Azure AD access token for your Power BI application, before you make calls to the Power BI REST APIs.

Para criar o cliente do Power BI com o token de acesso, crie um objeto de cliente do Power BI que permitirá interagir com as APIs REST do Power BI.To create the Power BI Client with your access token, create a Power BI client object, which allows you to interact with the Power BI REST APIs. Crie o objeto do cliente do Power BI encapsulando o AccessToken com um objeto Microsoft.Rest.TokenCredentials.You create the Power BI client object by wrapping the AccessToken with a Microsoft.Rest.TokenCredentials object.

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI Client object. it's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code to embed items.
}

Obter o relatório paginado que você deseja inserirGet the paginated report you want to embed

É possível usar o objeto do cliente do Power BI para recuperar uma referência ao item que deseja inserir.You can use the Power BI client object to retrieve a reference to the item you want to embed.

Veja um exemplo de código de como recuperar o primeiro relatório de um workspace específico.Here is a code sample of how to retrieve the first report from a given workspace.

Um exemplo de obtenção de um item de conteúdo, seja um bloco, um relatório ou um dashboard que você deseja inserir, está disponível no arquivo Services\EmbedService.cs no aplicativo de exemplo.A sample of getting a content item whether it's a report, dashboard, or tile that you want to embed is available within the Services\EmbedService.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// You need to provide the workspaceId where the dashboard resides.
ODataResponseListReport reports = await client.Reports.GetReportsInGroupAsync(workspaceId);

// Get the first report in the group.
Report report = reports.Value.FirstOrDefault();

Criar o token de inserçãoCreate the embed token

Gere um token de inserção, que pode ser usado nas APIs do Cliente de análise integrada do Power BI.Generate an embed token, which can be used from the Power BI embedded analytics Client APIs. Para criar um token inserido para inserir relatórios paginados do Power BI, use a API Reports GenerateTokenInGroup.To create an embedded token for embedding Power BI paginated reports, use the Reports GenerateTokenInGroup API.

Um exemplo de criação de um token de inserção está disponível no arquivo Services\EmbedService.cs no aplicativo de exemplo.A sample of creating an embed token is available within the Services\EmbedService.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Generate Embed Token.
var generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");
EmbedToken tokenResponse = client.Reports.GenerateTokenInGroup(workspaceId, report.Id, generateTokenRequestParameters);

// Generate Embed Configuration.
var embedConfig = new EmbedConfig()
{
    EmbedToken = tokenResponse,
    EmbedUrl = report.EmbedUrl,
    Id = report.Id
};

Carregar um item usando as APIs do ClienteLoad an item using the Client APIs

Você pode usar as APIs do cliente de análise integrada do Power BI para carregar um relatório paginado em um elemento div na sua página da Web.You can use the Power BI embedded analytics Client APIs to load a paginated report into a div element on your web page.

Para obter um exemplo completo de como usar a API do Cliente, use a ferramenta Playground.For a full sample of using the Client API, you can use the Playground tool. A ferramenta de Playground é uma maneira rápida de experimentar diferentes tipos de exemplos do Power BI Embedded.The Playground tool is a quick way to play with different types of Power BI Embedded samples. Você também pode obter mais informações sobre a API do Cliente de análise integrada do Power BI visitando a página APIs do Cliente de análise integrada do Power BI.You can also get more Information about the Power BI embedded analytics Client API by visiting the Power BI embedded analytics Client APIs page.

Próximas etapasNext steps

Neste tutorial, você aprendeu como inserir relatórios paginados do Power BI em um aplicativo para seus clientes.In this tutorial, you've learned how to embed Power BI paginated reports into an application for your customers. Você também pode tentar inserir o conteúdo do Power BI para seus clientes ou sua organização.You can also try to embed Power BI content for your customers or your organization.

Mais perguntas?More questions? Experimente perguntar à Comunidade do Power BITry asking the Power BI Community