Tutorial: Insira o conteúdo do Power BI usando um aplicativo de exemplo inserir para os clientesTutorial: Embed Power BI content using a sample embed for your customers application

A análise integrada e o Power BI Embedded (a oferta do Azure) permitem que você insira conteúdo do Power BI, como relatórios, dashboards e blocos, no seu aplicativo.Embedded analytics and Power BI Embedded (the Azure offer) allow you to embed Power BI content such as reports, dashboards and tiles, into your application.

Neste tutorial, você aprenderá como:In this tutorial, you'll learn how to:

  • Configure o seu ambiente inserido.Set up your embedded environment.
  • Configure um aplicativo de exemplo inserir para os clientes (também conhecido como aplicativo proprietário dos dados).Configure an embed for your customers (also known as app owns data) sample application.

Para usar o seu aplicativo, os usuários não precisarão entrar no Power BI ou ter uma licença do Power BI.To use your application, your users will not need to sign in to Power BI or have a Power BI license.

Será recomendável usar o método inserir para os clientes para inserir o seu conteúdo do Power BI, se você for um ISV (fornecedor independente de software) ou um desenvolvedor que deseja criar aplicativos para terceiros.We recommend using the embed for your customers method to embed your Power BI content, if you're an independent software vendor (ISV) or a developer, who wants to create applications for third parties.

Especificações de exemplo de códigoCode sample specifications

Este tutorial inclui instruções para configurar um aplicativo de exemplo inserir para os clientes em um dos seguintes frameworks:This tutorial includes instructions for configuring an embed for your customers sample application in one of the following frameworks:

  • .NET Framework.NET Framework
  • .NET Core.NET Core
  • JavaJava
  • Node JSNode JS
  • PythonPython

Os exemplos de código dão suporte aos seguintes navegadores:The code samples support the following browsers:

  • Microsoft EdgeMicrosoft Edge
  • Google ChromeGoogle Chrome
  • Mozilla FirefoxMozilla Firefox

Pré-requisitosPrerequisites

Antes de iniciar este tutorial, verifique se você tem as dependências do Power BI e do código listadas abaixo:Before you start this tutorial, verify that you have both the Power BI and code dependencies listed below:

MétodoMethod

Para criar um aplicativo de exemplo inserir para os clientes, siga estas etapas:To create an embed for your customers sample app, follow these steps:

  1. Selecione um método de autenticação.Select your authentication method.

  2. Registre um aplicativo do Azure AD.Register an Azure AD application.

  3. Crie um workspace do Power BI.Create a Power BI workspace.

  4. Crie e publique um relatório do Power BI.Create and publish a Power BI report.

  5. Obtenha os valores de parâmetro de inserção.Get the embedding parameter values.

  6. Acesso à API da entidade de serviçoService principal API access

  7. Habilite o acesso ao workspace.Enable workspace access.

  8. Insira o conteúdo.Embed your content.

Etapa 1 – Selecionar um método de autenticaçãoStep 1 - Select your authentication method

A sua solução inserida será diferente de acordo com o método de autenticação selecionado.Your embedded solution will vary depending on the authentication method you select. Portanto, é importante entender as diferenças entre os métodos de autenticação e decidir qual deles é mais adequado à sua solução.Therefore, it's important to understand the differences between the authentication methods, and decide which one best suits your solution.

A tabela a seguir descreve algumas diferenças importantes entre os métodos de autenticação entidade de serviço e usuário mestre.The table below describes a few key differences between the service principal and master user authentication methods.

ConsideraçãoConsideration Entidade de serviçoService principal Usuário mestreMaster user
MecanismoMechanism O objeto de entidade de serviço do seu aplicativo do Azure AD permite que o Azure AD autentique o seu aplicativo de solução inserido no Power BI.Your Azure AD app's service principal object allows Azure AD to authenticate your embedded solution app against Power BI. O seu aplicativo do Azure AD usa as credenciais (nome de usuário e senha) de um usuário do Power BI para se autenticar no Power BI.Your Azure AD app uses the credentials (username and password) of a Power BI user, to authenticate against Power BI.
SegurançaSecurity A entidade de serviço é o método de autorização recomendado do Azure AD.Service principal is the Azure AD recommended authorization method. Se você estiver usando uma entidade de serviço*, poderá se autenticar usando um segredo do aplicativo ou um certificado.If you're using a service principal,* you can authenticate using either an application secret or a certificate.

Este tutorial descreve apenas o uso da entidade de serviço com um segredo do aplicativo.This tutorial only describes using service principal with an application secret. Para inserir usando uma entidade de serviço e um certificado, confira o artigo Entidade de serviço com um certificado.To embed using a service principal and a certificate, refer to the service principal with a certificate article.
Esse método de autenticação não é considerado tão seguro quanto usar uma entidade de serviço.This authentication method is not considered as secure as using a service principal. Isso ocorre porque você precisa estar atento às credenciais do usuário mestre (nome de usuário e senha).This is because you have to be vigilant with the master user credentials (username and password). Por exemplo, você não deve expô-las no seu aplicativo de inserção e alterar a senha com frequência.For example, you must not expose them in your embedding application, and you should change the password frequently.
Permissões delegadas do Azure ADAzure AD delegated permissions Não necessário.Not required. O usuário mestre ou um administrador precisam consentir que o seu aplicativo acesse as permissões de API REST do Power BI (também conhecidas como escopos).Your master user or an administrator has to grant consent for your app to access Power BI REST API permissions (also known as scopes). Por exemplo, Report.ReadWrite.All.For example, Report.ReadWrite.All.
Acesso ao serviço do Power BIPower BI service access Você não pode acessar um serviço do Power BI com uma entidade de serviço.You can't access Power BI service with a service principal. Você pode acessar um serviço do Power BI com as suas credenciais de usuário mestre.You can access Power BI service with your master user credentials.
LicençaLicense Não requer uma licença Pro.Doesn't require a Pro license. Você pode usar o conteúdo de qualquer workspace do qual você é membro ou administrador.You can use content from any workspace that you're a member or an admin of. Exige obter uma licença do Power BI Pro ou PPU (Premium por usuário).Requires a Power BI Pro or Premium Per User (PPU) license.

Etapa 2 – Registrar um aplicativo do Azure ADStep 2 - Register an Azure AD application

Registrar o seu aplicativo com o Azure AD permite que você:Registering your application with Azure AD allows you to:

Para registrar o seu aplicativo com o Azure AD, siga as instruções em Registrar o seu aplicativo.To register your application with Azure AD, follow the instructions in Register your application.

Observação

Antes de registrar o seu aplicativo, você precisará decidir qual método de autenticação usar, entidade de serviço ou usuário mestre.Before registering your application, you'll need to decide which authentication method to use, service principal or master user.

Etapa 3 – Criar um workspace do Power BIStep 3 - Create a Power BI workspace

O Power BI mantém os seus relatórios, dashboards e blocos em um workspace.Power BI keeps your reports, dashboards, and tiles in a workspace. Para inserir esses itens, você precisará criá-los e carregá-los em um workspace.To embed these items, you'll need to create them and upload them into a workspace.

Dica

Se você já tiver um workspace, pule esta etapa.If you already have a workspace, you can skip this step.

Para criar um workspace, faça o seguinte:To create a workspace, do the following:

  1. Entre no Power BI.Sign in to Power BI.

  2. Selecione Workspaces.Select Workspaces.

  3. Selecione Criar um workspace.Select Create a workspace.

  4. Nomeie o seu workspace e selecione Salvar.Name your workspace and select Save.

Etapa 4 – Criar e publicar um relatório do Power BIStep 4 - Create and publish a Power BI report

A próxima etapa é criar um relatório e carregá-lo no seu workspace.Your next step is to create a report and upload it to your workspace. Você pode criar o próprio relatório usando o Power BI Desktop e, em seguida, publicá-lo no seu workspace.You can create your own report using Power BI Desktop, and then publish it to your workspace. Ou pode carregar um relatório de exemplo no seu workspace.Or, you can upload a sample report to your workspace.

Dica

Se você já tiver um workspace com um relatório, pule esta etapa.If you already have a workspace with a report, you can skip this step.

Para baixar um relatório de exemplo e publicá-lo no seu workspace, siga estas etapas:To download a sample report and publish it to your workspace, follow these steps:

  1. Abra a pasta Exemplos do Power BI Desktop do GitHub.Open the GitHub Power BI Desktop samples folder.

  2. Selecione Código e Baixar zip.Select Code and then select Download zip.

    Uma captura de tela que mostra a opção de download do ZIP no GitHub de exemplos no Power BI Desktop

  3. Extraia o ZIP baixado e navegue até a pasta Relatórios de Exemplos.Extract the downloaded ZIP and navigate to the Samples Reports folder.

  4. Selecione um relatório a ser inserido e publique-o no seu workspace.Select a report to embed, and publish it to your workspace.

Etapa 5 – Obter os valores de parâmetro de inserçãoStep 5 - Get the embedding parameter values

Para inserir o seu conteúdo, você precisará obter determinados valores de parâmetro.To embed your content, you'll need to obtain certain parameter values. A tabela abaixo mostra os valores necessários e indica se eles se aplicam aos métodos de autenticação entidade de serviço, usuário mestre ou ambos.The table below shows the required values, and indicates if they're applicable to the service principal authentication method, the master user authentication method, or both.

Antes de inserir o conteúdo, verifique se você tem todos os valores listados abaixo.Before you embed your content, make sure you have all the values listed below. Alguns dos valores serão diferentes, dependendo do método de autenticação que você estiver usando.Some of the values will differ, depending on the authentication method you're using.

ParâmetroParameter Entidade de serviçoService principal Usuário mestreMaster user
ID do ClienteClient ID Aplica-se a. Aplica-se a.
ID do WorkspaceWorkspace ID Aplica-se a. Aplica-se a.
ID do RelatórioReport ID Aplica-se a. Aplica-se a.
Segredo do clienteClient secret Aplica-se a. Não se aplica a.
ID do locatárioTenant ID Aplica-se a. Não se aplica a.
Nome de usuário do Power BIPower BI username Não se aplica a. Aplica-se a.
Senha do Power BIPower BI password Não se aplica a. Aplica-se a.

ID do ClienteClient ID

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Aplica-se ao.Usuário mestreApplies to: Applies to.Service principal Applies to.Master user

Para obter o GUID da ID do cliente (também conhecido como ID do aplicativo), siga estas etapas:To get the client ID GUID (also know as application ID), follow these steps:

  1. Entre no Microsoft Azure.Log into Microsoft Azure.

  2. Pesquise Registros de aplicativo e selecione o link Registros de aplicativo.Search for App registrations and select the App registrations link.

  3. Selecione o aplicativo do Azure AD que você está usando para inserir o seu conteúdo do Power BI.Select the Azure AD app your using for embedding your Power BI content.

  4. Na seção Visão geral, copie o GUID da ID do aplicativo (cliente) .From the Overview section, copy the Application (client) ID GUID.

ID do workspaceWorkspace ID

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Aplica-se ao.Usuário mestreApplies to: Applies to.Service principal Applies to.Master user

Para obter o GUID da ID do workspace, siga estas etapas:To get the workspace ID GUID, follow these steps:

  1. Entre no serviço do Power BI.Sign in to Power BI service.

  2. Abra o relatório que deseja inserir.Open the report you want to embed.

  3. Copie o GUID da URL.Copy the GUID from the URL. O GUID é o número entre /groups/ e /reports/ .The GUID is the number between /groups/ and /reports/.

    Uma captura de tela que mostra o GUID da ID do workspace na URL do serviço do Power BI

ID do RelatórioReport ID

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Aplica-se ao.Usuário mestreApplies to: Applies to.Service principal Applies to.Master user

Para obter o GUID da ID do relatório, siga estas etapas:To get the report ID GUID, follow these steps:

  1. Entre no serviço do Power BI.Sign in to Power BI service.

  2. Abra o relatório que deseja inserir.Open the report you want to embed.

  3. Copie o GUID da URL.Copy the GUID from the URL. O GUID é o número entre /reports/ e /ReportSection.The GUID is the number between /reports/ and /ReportSection.

    Uma captura de tela que mostra o GUID da ID do relatório na URL do serviço do Power BI

Segredo do clienteClient secret

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Não se aplica ao.Usuário mestreApplies to: Applies to.Service principal Does not apply to.Master user

Para obter o segredo do cliente, siga estas etapas:To get the client secret, follow these steps:

  1. Entre no Microsoft Azure.Log into Microsoft Azure.

  2. Pesquise Registros de aplicativo e selecione o link Registros de aplicativo.Search for App registrations and select the App registrations link.

  3. Selecione o aplicativo do Azure AD que você está usando para inserir o seu conteúdo do Power BI.Select the Azure AD app your using for embedding your Power BI content.

  4. Em Gerenciar, selecione Certificados e Segredos.Under Manage, select Certificates & secrets.

  5. Em Segredos do cliente, selecione Novo segredo do cliente.Under Client secrets, select New client secret.

  6. Na janela pop-up Adicionar um segredo do cliente, forneça uma descrição do segredo do aplicativo, selecione quando o segredo do aplicativo expira e selecione Adicionar.In the Add a client secret pop-up window, provide a description for your application secret, select when the application secret expires, and select Add.

  7. Na seção Segredos do cliente, copie a cadeia de caracteres na coluna Valor do segredo do aplicativo recém-criado.From the Client secrets section, copy the string in the Value column of the newly created application secret. O valor do segredo do cliente é a sua ID do cliente.The client secret value is your client ID.

Observação

Copie o valor do segredo do cliente quando aparecer pela primeira vez.Make sure you copy the client secret value when it first appears. Depois de navegar para fora dessa página, o segredo do cliente ficará oculto e você não poderá recuperar seu valor.After navigating away from this page, the client secret will be hidden and you'll not be able to retrieve its value.

ID do locatárioTenant ID

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Não se aplica ao.Usuário mestreApplies to: Applies to.Service principal Does not apply to.Master user

Para obter o GUID da ID do locatário, siga estas etapas:To get the tenant ID GUID, follow these steps:

  1. Entre no Microsoft Azure.Log into Microsoft Azure.

  2. Pesquise Registros de aplicativo e selecione o link Registros de aplicativo.Search for App registrations and select the App registrations link.

  3. Selecione o aplicativo do Azure AD que você está usando para inserir o seu conteúdo do Power BI.Select the Azure AD app you're using for embedding your Power BI content.

  4. Na seção Visão geral, copie o GUID da ID do diretório (locatário) .From the Overview section, copy the Directory (tenant) ID GUID.

Nome de usuário e senha do Power BIPower BI username and password

Dica

Aplica-se a: Não se aplica à.Entidade de serviço Aplica-se ao.Usuário mestreApplies to: Does not apply to.Service principal Applies to.Master user

Obtenha o nome de usuário e a senha do usuário do Power BI que você está usando como usuário mestre.Obtain the username and password of the Power BI user you're using as your master user. Esse é o mesmo usuário usado no serviço do Power BI para criar um workspace e carregar um relatório.This is the same user you used to create a workspace and upload a report to, in Power BI service.

Etapa 6 – Acesso à API da entidade de serviçoStep 6 - Service principal API access

Dica

Aplica-se a: Aplica-se à.Entidade de serviço Não se aplica ao.Usuário mestreApplies to: Applies to.Service principal Does not apply to.Master user

Esta etapa só será relevante se você estiver usando o método de autenticação entidade de serviço.This step is only relevant if you're using the service principal authentication method. Se você estiver usando um usuário mestre, ignore esta etapa e continue com Etapa 7 – Habilitar o acesso ao workspace.If you're using a master user, skip this step and continue with Step 7 - Enable workspace access.

Para que um aplicativo do Azure AD possa acessar o conteúdo e as APIs do Power BI, um administrador de Power BI precisa habilitar o acesso à entidade de serviço no portal de administração do Power BI.For an Azure AD app to be able to access the Power BI content and APIs, a Power BI admin needs to enable service principal access in the Power BI admin portal. Se você não for o administrador do seu locatário, peça ao administrador do locatário que habilite as Configurações de locatário para você.If you're not the admin of your tenant, get the tenant's admin to enable the Tenant settings for you.

  1. Em Serviço do Power BI, selecione Configurações > Configurações > Portal de administração.In Power BI service, select Settings > Settings > Admin portal.

    Uma captura de tela que mostra a opção de menu configurações de administrador no menu de configurações do serviço do Power BI

  2. Selecione Configurações de locatário e role para baixo até a seção Configurações do desenvolvedor.Select Tenant settings and then scroll down to the Developer settings section.

  3. Expanda Permitir que as entidades de serviço usem as APIs do Power BI e habilite essa opção.Expand Allow service principals to use Power BI APIs, and enable this option.

    Uma captura de tela que mostra como habilitar a opção de configurações do desenvolvedor, na opção de menu configurações de locatário, no serviço do Power BI

Observação

Ao usar uma entidade de serviço, é recomendável limitar o acesso às configurações de locatário usando um grupo de segurança.When using a service principal, it's recommended to limit its access to the tenant settings using a security group. Para saber mais sobre esse recurso, confira estas seções no artigo da entidade de serviço:To learn more about this feature, see these sections in the service principal article:

Etapa 7 – Habilitar o acesso ao workspaceStep 7 - Enable workspace access

Para habilitar que o aplicativo do Azure AD acesse artefatos, como relatórios, dashboards e conjuntos de dados no serviço do Power BI, adicione a entidade de serviço ou o usuário mestre como um membro ou administrador do seu workspace.To enable your Azure AD app access artifacts such as reports, dashboards and datasets in the Power BI service, add the service principal or master user, as a member or admin to your workspace.

  1. Entre no serviço do Power BI.Sign in to Power BI service.

  2. Role até o espaço de trabalho para o qual você deseja habilitar o acesso e, no menu Mais, selecione Acesso do espaço de trabalho.Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.

    Captura de tela mostrando o botão de acesso do workspace no menu Mais de um workspace do Power BI.

  3. No painel Acesso, dependendo do método de autenticação que você está usando, copie a entidade de serviço ou o usuário mestre na caixa de texto Inserir o endereço de email.In the Access pane, depending on which authentication method you're using, copy the service principal or master user to the Enter email address text box.

    Observação

    Se você estiver usando uma entidade de serviço, o nome dela será o nome que você atribuiu ao seu aplicativo do Azure AD.If you're using a service principal, its name is the name you gave your Azure AD app.

  4. Selecione Adicionar.Select Add.

Etapa 8 – Inserir o seu conteúdoStep 8 - Embed your content

O aplicativo de exemplo inserido do Power BI permite que você crie um aplicativo inserir para os clientes do Power BI.The Power BI embedded sample application allows you to create an embed for your customers Power BI app.

Siga estas etapas para modificar o aplicativo de exemplo inserir para os clientes, para inserir o seu relatório do Power BI.Follow these steps to modify the embed for your customers sample application, to embed your Power BI report.

  1. Abra a pasta Exemplos de desenvolvedores do Power BI.Open the Power BI developer samples folder.

  2. Selecione Código e Baixar zip.Select Code and then select Download zip.

    Uma captura de tela que mostra a opção de download do ZIP no GitHub de exemplos do desenvolvedor do Power BI

  3. Extraia o ZIP baixado e navegue até a pasta PowerBI-Developer-Samples-master.Extract the downloaded ZIP and navigate to the PowerBI-Developer-Samples-master folder.

  1. Dependendo do idioma que você deseja que o seu aplicativo use, abra uma destas pastas:Depending on the language you want your application to use, open one of these folders:

    • .NET Core.NET Core
    • .NET Framework.NET Framework
    • JavaJava
    • Node JSNode JS
    • PythonPython

    Observação

    Os aplicativos de exemplo inserir para os clientes dão suporte apenas aos frameworks listados acima.The embed for your customers sample applications only support the frameworks listed above. O aplicativo de exemplo React dá suporte apenas à solução inserir para a organização .The React sample application only supports the embed for your organization solution.

  2. Abra a pasta Inserir para os clientes.Open the Embed for your customers folder.

  1. Abra o aplicativo de exemplo inserir para os clientes usando um destes métodos:Open the embed for your customers sample app using one of these methods:

  2. Abra appsettings.json.Open appsettings.json.

  3. Dependendo do seu método de autenticação, preencha os seguintes valores de parâmetro:Depending on your authentication method, fill in the following parameter values:

    ParâmetroParameter Entidade de serviçoService principal Usuário mestreMaster user
    AuthenticationMode ServicePrincipalServicePrincipal MasterUserMasterUser
    ClientId A ID do cliente do seu aplicativo do Azure ADYour Azure AD app client ID A ID do cliente do seu aplicativo do Azure ADYour Azure AD app client ID
    TenantId A ID do locatário do seu Azure ADYour Azure AD tenant ID N/DN/A
    PbiUsername N/DN/A O seu nome de usuário do usuário mestre, confira Nome de usuário e senha do Power BIYour master user username, see Power BI username and password
    PbiPassword N/DN/A A sua senha do usuário mestre, confira Nome de usuário e senha do Power BIYour master user password, see Power BI username and password
    ClientSecret O seu segredo do cliente do Azure ADYour Azure AD client secret N/DN/A
    WorkspaceId A ID do workspace com o relatório inserido; confira ID do workspaceThe ID of the workspace with your embedded report, see Workspace ID A ID do workspace com o relatório inserido; confira ID do workspaceThe ID of the workspace with your embedded report, see Workspace ID
    ReportId A ID do relatório que você está inserindo; confira ID do relatórioThe ID of the report you're embedding, see Report ID A ID do relatório que você está inserindo; confira ID do relatórioThe ID of the report you're embedding, see Report ID
  4. Execute o projeto selecionando a opção adequada:Run the project by selecting the appropriate option:

    • Se você estiver usando o Visual Studio, selecione IIS Express (reprodução).If you're using Visual Studio, select IIS Express (play).

    • Se você estiver usando o Visual Studio Code, selecione Executar > Iniciar Depuração.If you're using Visual Studio Code, select Run > Start Debugging.

Desenvolvendo seu aplicativoDeveloping your application

Depois de configurar e executar a aplicativo de exemplo inserir para os clientes, você pode começar a desenvolver o próprio aplicativo.After configuring and running the embed for your customers sample application, you can start developing your own application.

Quando estiver pronto, examine os requisitos para mover para a produção.When you're ready, review the move to production requirements. Você também precisará de uma capacidade e deve examinar o artigo sobre planejamento da capacidade para estabelecer qual SKU é mais adequado às suas necessidades.You'll also need a capacity, and should review the capacity planning article to establish which SKU best suites your needs.

Próximas etapasNext steps