Tutorial: Incorporar conteúdo do Power BI usando uma incorporação de exemplo para o aplicativo de seus clientes

APLICA-SE A: App possui dados O usuário possui dados

A análise incorporada e o Power BI Embedded (a oferta do Azure) permitem incorporar conteúdo do Power BI, como relatórios, painéis e blocos, em seu aplicativo.

Neste tutorial, irá aprender a:

  • Configure seu ambiente incorporado.
  • Configure um aplicativo de exemplo de incorporação para seus clientes (também conhecido como aplicativo possui dados).

Para usar seu aplicativo, seus usuários não precisarão entrar no Power BI ou ter uma licença do Power BI.

Recomendamos usar o método incorporar para seus clientes para incorporar seu conteúdo do Power BI, se você for um fornecedor independente de software (ISV) ou um desenvolvedor, que deseja criar aplicativos para terceiros.

Importante

Se você estiver incorporando conteúdo para uma nuvem nacional/regional, as primeiras etapas deste tutorial serão diferentes. Consulte Incorporar conteúdo para nuvens nacionais/regionais para obter detalhes.

Especificações de exemplo de código

Este tutorial inclui instruções para configurar um aplicativo de exemplo de incorporação para seus clientes em uma das seguintes estruturas:

  • .NET Framework
  • .NET Core
  • Java
  • Node JS
  • Python

Os exemplos de código suportam os seguintes navegadores:

  • Microsoft Edge
  • Google Chrome
  • Mozilla Firefox

Pré-requisitos

Antes de iniciar este tutorial, verifique se você tem as dependências do Power BI e do código listadas abaixo:

Método

Para criar uma incorporação para seu aplicativo de exemplo de clientes , siga estas etapas:

  1. Selecione seu método de autenticação.

  2. Registre um aplicativo Microsoft Entra.

  3. Crie um espaço de trabalho do Power BI.

  4. Crie e publique um relatório do Power BI.

  5. Obtenha os valores dos parâmetros de incorporação.

  6. Acesso à API da entidade de serviço

  7. Habilite o acesso ao espaço de trabalho.

  8. Incorpore o seu conteúdo.

Etapa 1 - Selecione seu método de autenticação

Sua solução incorporada variará dependendo do método de autenticação selecionado. Portanto, é importante entender as diferenças entre os métodos de autenticação e decidir qual deles melhor se adapta à sua solução.

A tabela abaixo descreve algumas diferenças importantes entre os métodos de autenticação da entidade de serviço e do usuário mestre.

Consideração Service principal (Principal de serviço) Utilizador principal
Mecanismo O objeto principal de serviço do aplicativo Microsoft Entra permite que a ID do Microsoft Entra autentique seu aplicativo de solução incorporado no Power BI. Seu aplicativo Microsoft Entra usa as credenciais (nome de usuário e senha) de um usuário do Power BI para autenticar no Power BI.
Segurança A entidade de serviço é o método de autorização recomendado pelo Microsoft Entra ID. Se você estiver usando uma entidade de serviço, poderá autenticar usando um segredo de aplicativo ou um certificado.

Este tutorial descreve apenas o uso da entidade de serviço com um segredo de aplicativo. Para incorporar usando uma entidade de serviço e um certificado, consulte a entidade de serviço com um artigo de certificado.
Esse método de autenticação não é tão seguro quanto uma entidade de serviço. Você tem que estar atento com as credenciais de usuário mestre (nome de usuário e senha). Por exemplo, não os exponha em seu aplicativo de incorporação e altere a senha com frequência.
Permissões delegadas do Microsoft Entra ID Não necessário. Seu usuário mestre ou um administrador precisa conceder consentimento para que seu aplicativo acesse as permissões da API REST do Power BI (também conhecidas como escopos). Por exemplo, Report.ReadWrite.All.
Acesso ao serviço do Power BI Não é possível acessar o serviço do Power BI com uma entidade de serviço. Você pode acessar o serviço do Power BI com suas credenciais de usuário mestre.
Licença Não requer uma licença Pro. Você pode usar o conteúdo de qualquer espaço de trabalho do qual seja membro ou administrador. Requer uma licença do Power BI Pro ou Premium por usuário (PPU).

Etapa 2 - Registrar um aplicativo Microsoft Entra

Registar a sua candidatura com o Microsoft Entra ID permite-lhe:

  • Estabelecer uma identidade para seu aplicativo
  • Permitir que seu aplicativo acesse as APIs REST do Power BI
  • Se estiver a utilizar um utilizador mestre - Especifique as permissões REST do Power BI da sua aplicação

Para registar a sua candidatura com o Microsoft Entra ID, siga as instruções em Registar a sua candidatura.

Nota

Antes de registrar seu aplicativo, você precisará decidir qual método de autenticação usar, entidade de serviço ou usuário mestre.

Etapa 3 - Criar um espaço de trabalho do Power BI

O Power BI mantém seus relatórios, painéis e blocos em um espaço de trabalho. Para incorporar esses itens, você precisará criá-los e carregá-los em um espaço de trabalho.

Gorjeta

Se já tiver um espaço de trabalho, pode ignorar este passo.

Para criar um espaço de trabalho, faça o seguinte:

  1. Inicie sessão no Power BI.

  2. Selecione Áreas de trabalho.

  3. Selecione Criar uma área de trabalho.

  4. Nomeie seu espaço de trabalho e selecione Salvar.

Etapa 4 - Criar e publicar um relatório do Power BI

Sua próxima etapa é criar um relatório e carregá-lo em seu espaço de trabalho. Você pode criar seu próprio relatório usando o Power BI Desktop e publicá-loem seu espaço de trabalho. Ou, você pode carregar um relatório de exemplo para seu espaço de trabalho.

Gorjeta

Se já tiver uma área de trabalho com um relatório, pode ignorar este passo.

Para baixar um relatório de exemplo e publicá-lo em seu espaço de trabalho, siga estas etapas:

  1. Abra a pasta de exemplos do GitHub Power BI Desktop.

  2. Selecione Código e, em seguida, selecione Baixar zip.

    A screenshot showing the ZIP download option in the Power B I desktop samples GitHub

  3. Extraia o ZIP baixado e navegue até a pasta Relatórios de exemplo .

  4. Selecione um relatório para incorporar e publique-o no seu espaço de trabalho.

Etapa 5 - Obter os valores dos parâmetros de incorporação

Para incorporar seu conteúdo, você precisa obter determinados valores de parâmetro. A tabela abaixo mostra os valores necessários e indica se eles são aplicáveis ao método de autenticação da entidade de serviço, ao método de autenticação do usuário mestre ou a ambos.

Antes de incorporar seu conteúdo, verifique se você tem todos os valores listados abaixo. Alguns dos valores serão diferentes, dependendo do método de autenticação que você está usando.

Parâmetro Service principal (Principal de serviço) Utilizador principal
ID de Cliente Applies to. Applies to.
ID do espaço de trabalho Applies to. Applies to.
ID do relatório Applies to. Applies to.
Segredo do cliente Applies to. Does not apply to.
ID do Inquilino Applies to. necessário apenas para o Nó JS
Nome de usuário do Power BI Does not apply to. Applies to.
Palavra-passe do Power BI Does not apply to. Applies to.

ID de Cliente

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Applies to.do serviço

Para obter o GUID da ID do cliente (também conhecido como ID do aplicativo), siga estas etapas:

  1. Faça logon no Microsoft Azure.

  2. Pesquise por Registos de aplicações e selecione a ligação Registos de aplicações.

  3. Selecione o aplicativo Microsoft Entra que você está usando para incorporar seu conteúdo do Power BI.

  4. Na seção Visão geral, copie o GUID do ID do aplicativo (cliente).

ID da área de trabalho

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Applies to.do serviço

Para obter o GUID do ID do espaço de trabalho, siga estas etapas:

  1. Iniciar sessão no serviço Power BI.

  2. Abra o relatório que pretende incorporar.

  3. Copie o GUID do URL. O GUID é o número entre /groups/ e /reports/.

    A screenshot showing workspace ID GUID in the Power B I service U R L

Como alternativa, você pode encontrar o ID do espaço de trabalho nas configurações do Portal de administração selecionando Detalhes ao lado do nome do espaço de trabalho.

A screenshot showing how to find the workspace I D from the admin settings.

ID do relatório

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Applies to.do serviço

Para obter o GUID de ID de relatório, siga estas etapas:

  1. Iniciar sessão no serviço Power BI.

  2. Abra o relatório que pretende incorporar.

  3. Copie o GUID do URL. O GUID é o número entre /reports/ e /ReportSection.

    A screenshot showing report ID GUID in the Power B I service U R L

Segredo do cliente

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Does not apply to.do serviço

Para obter o segredo do cliente, siga estes passos:

  1. Faça logon no Microsoft Azure.

  2. Pesquise por Registos de aplicações e selecione a ligação Registos de aplicações.

  3. Selecione o aplicativo Microsoft Entra que você está usando para incorporar seu conteúdo do Power BI.

  4. Em Gerenciar, selecione Certificados & segredos.

  5. Em Segredos do cliente, selecione Novo segredo do cliente.

  6. Na janela pop-up Adicionar um segredo do cliente, forneça uma descrição para o segredo do aplicativo, selecione quando o segredo do aplicativo expira e selecione Adicionar.

  7. Na seção Segredos do cliente, copie a cadeia de caracteres na coluna Valor do segredo do aplicativo recém-criado. O valor secreto do cliente é o ID do cliente.

Nota

Certifique-se de copiar o valor secreto do cliente quando ele aparecer pela primeira vez. Depois de navegar para fora desta página, o segredo do cliente será oculto e você não poderá recuperar seu valor.

ID de Inquilino do

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Does not apply to.do serviço

Para obter o GUID de ID do locatário, siga estas etapas:

  1. Faça logon no Microsoft Azure.

  2. Pesquise por Registos de aplicações e selecione a ligação Registos de aplicações.

  3. Selecione o aplicativo Microsoft Entra que você está usando para incorporar seu conteúdo do Power BI.

  4. Na seção Visão geral, copie o GUID de ID do diretório (locatário).

Nome de utilizador e palavra-passe do Power BI

Gorjeta

Aplica-se a:Does not apply to.Usuário mestre principal Applies to.do serviço

Obtenha o nome de usuário e a senha do usuário do Power BI que você está usando como seu usuário mestre. Este é o mesmo usuário que você usou para criar um espaço de trabalho e carregar um relatório, no serviço do Power BI.

Etapa 6 - Acesso à API da entidade de serviço

Gorjeta

Aplica-se a:Applies to.Usuário mestre principal Does not apply to.do serviço

Esta etapa só é relevante se você estiver usando o método de autenticação da entidade de serviço. Se você estiver usando um usuário mestre, ignore esta etapa e continue com a Etapa 7 - Habilitar acesso ao espaço de trabalho.

Para que um aplicativo Microsoft Entra possa acessar o conteúdo e as APIs do Power BI, um administrador do Power BI precisa habilitar o acesso da entidade de serviço no portal de administração do Power BI. Se não for o administrador do seu inquilino, peça ao administrador do inquilino para ativar as definições de Inquilino para si.

  1. No serviço Power BI, selecione Configurações>Portal de administração de configurações>.

    A screenshot showing the admin settings menu option in the Power B I service settings menu.

  2. Selecione Configurações do locatário e role para baixo até a seção Configurações do desenvolvedor .

  3. Expanda Permitir que as entidades de serviço usem APIs do Power BI e habilite essa opção.

    A screenshot showing how to enable the developer settings option, in the tenant settings menu option, in Power B I service.

Nota

Ao usar uma entidade de serviço, é recomendável limitar seu acesso às configurações do locatário usando um grupo de segurança. Para saber mais sobre esse recurso, consulte estas seções no artigo da entidade de serviço:

Etapa 7 - Habilitar o acesso ao espaço de trabalho

Para permitir que seu aplicativo Microsoft Entra acesse objetos como relatórios, painéis e modelos semânticos no serviço Power BI, adicione a entidade de serviço ou usuário mestre, como membro ou administrador ao seu espaço de trabalho.

  1. Iniciar sessão no serviço Power BI.

  2. Desloque-se para a área de trabalho para a qual pretende ativar o acesso e, no menu Mais, selecione Acesso à área de trabalho.

    Screenshot showing the workspace access button in the more menu of a Power B I workspace.

  3. No painel Acesso, dependendo do método de autenticação que estiver a utilizar, copie a entidade de serviço ou o utilizador mestre para a caixa de texto Introduzir endereço de e-mail.

    Nota

    Se você estiver usando uma entidade de serviço, seu nome será o nome que você deu ao seu aplicativo Microsoft Entra.

  4. Selecione Adicionar.

Etapa 8 - Incorporar seu conteúdo

O aplicativo de exemplo incorporado do Power BI permite que você crie uma incorporação para o aplicativo Power BI de seus clientes .

Siga estas etapas para modificar a incorporação para seu aplicativo de exemplo de clientes , para incorporar seu relatório do Power BI.

  1. Abra a pasta de exemplos do desenvolvedor do Power BI.

  2. Selecione Código e, em seguida, selecione Baixar zip.

    A screenshot showing the ZIP download option in the Power B I developer samples GitHub

  3. Extraia o ZIP baixado e navegue até a pasta PowerBI-Developer-Samples-master .

  1. Dependendo do idioma que você deseja que seu aplicativo use, abra uma destas pastas:

    • .NET Core
    • .NET Framework
    • Java
    • Node JS
    • Python

    Nota

    Os aplicativos de exemplo de incorporação para seus clientes suportam apenas as estruturas listadas acima. O aplicativo de exemplo React suporta apenas a incorporação para a solução da sua organização .

  2. Abra a pasta Incorporar para seus clientes .

  1. Abra o aplicativo de exemplo de incorporação para seus clientes usando um destes métodos:

  2. Abra appsettings.json.

  3. Dependendo do seu método de autenticação, preencha os seguintes valores de parâmetro:

    Parâmetro Service principal (Principal de serviço) Utilizador principal
    AuthenticationMode ServicePrincipal Utilizador Mestre
    ClientId Sua ID de cliente do aplicativo Microsoft Entra Sua ID de cliente do aplicativo Microsoft Entra
    TenantId O seu ID de inquilino do Microsoft Entra N/A
    PbiUsername N/A Seu nome de usuário mestre , consulte Nome de usuário e senha do Power BI
    PbiPassword N/A Sua senha de usuário mestre, consulte Nome de usuário e senha do Power BI
    ClientSecret O segredo do cliente Microsoft Entra ID N/A
    WorkspaceId A ID do espaço de trabalho com seu relatório incorporado, consulte ID do espaço de trabalho A ID do espaço de trabalho com seu relatório incorporado, consulte ID do espaço de trabalho
    ReportId A ID do relatório que você está incorporando, consulte ID do relatório A ID do relatório que você está incorporando, consulte ID do relatório
  4. Execute o projeto selecionando a opção apropriada:

    • Se você estiver usando o Visual Studio, selecione IIS Express (reproduzir).

    • Se você estiver usando o Visual Studio Code, selecione Executar > Iniciar Depuração.

Desenvolvendo seu aplicativo

Depois de configurar e executar a incorporação para seu aplicativo de exemplo de clientes, você pode começar a desenvolver seu próprio aplicativo.

Experimente o playground de análise incorporada do Power BI para começar a desenvolver e acompanhar todos os novos recursos e atualizações do Power BI Embedded.

Quando estiver pronto, revise a mudança para os requisitos de produção . Você também precisará de uma capacidade e deve revisar o artigo de planejamento de capacidade para estabelecer qual SKU melhor atende às suas necessidades.

Importante

Se você usou tokens de avaliação de incorporação gratuita para desenvolvimento, deverá comprar uma capacidade de produção. Até que uma capacidade seja comprada, o banner da versão de avaliação gratuita continuará a aparecer na parte superior do relatório incorporado.

Tem dúvidas? Pergunte à Comunidade do Power BI.