Partilhar via

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

APLICA-SE A: A app possui os dados O utilizador possui os 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 precisam 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
  • Núcleo do .NET
  • 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 seguintes dependências do Power BI e do código:

  • Dependências do Power BI

    • O seu próprio tenant do Microsoft Entra.

    • Para autenticar seu aplicativo no Power BI, você precisa de uma das seguintes opções:

      • Entidade de serviço - um objeto principal de serviço do Microsoft Entra que permite que a ID do Microsoft Entra autentique seu aplicativo.

      • Licença do Power BI Pro - Este é o seu utilizador mestre e a sua aplicação utiliza-a para se autenticar no Power BI.

      • Uma licença Power BI Premium Por Utilizador (PPU) - Este é o seu utilizador mestre e a sua aplicação o utiliza para autenticar no Power BI.

      Nota

      Para passar para a produção , você precisará de uma capacidade.

  • Dependências de código

Método

Para criar uma incorporação para o seu aplicativo de exemplo destinado a 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 varia 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 a seguir descreve algumas diferenças importantes entre os métodos de autenticação da entidade de serviço e do usuário mestre.

Consideração 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 O principal do serviço é o método de autorização recomendado do Microsoft Entra ID. Se estiver a usar uma entidade de serviço, pode autenticar utilizando 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 o artigo sobre a entidade de serviço com um certificado.		 Este método de autenticação não é tão seguro quanto um principal 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 Power BI Pro ou Premium por utilizador (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 o seu aplicativo, precisará decidir qual método de autenticação usar, principal de serviço ou utilizador principal.

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

O Microsoft Fabric mantém seus relatórios, painéis e blocos em um espaço de trabalho. Para incorporar esses itens, você precisa 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. Faça login no Fabric.
  2. Selecione Áreas de trabalho.
  3. Selecione + Novo espaço de trabalho.
  4. Nomeie seu espaço de trabalho e selecione Aplicar.

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 (não habilitado para Direct Lake) e publicá-lo em seu espaço de trabalho, siga estas etapas:

  1. Abra a pasta Power BI Desktop samples do GitHub.

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

    Uma captura de tela mostrando a opção de download ZIP no GitHub de exemplos de área de trabalho do Power B I

  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.

Nota

Se o seu relatório usa um modelo semântico Direct Lake, certifique-se de revisar essas limitações.

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 a seguir 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 podem diferir, dependendo do método de autenticação que você está usando.

Parâmetro Principal de serviço Utilizador principal
ID de Cliente Aplica-se a. Aplica-se a.
ID do espaço de trabalho Aplica-se a. Aplica-se a.
ID do relatório Aplica-se a. Aplica-se a.
Segredo do cliente Aplica-se a. Não se aplica a.
ID do Inquilino Aplica-se a. necessário apenas para o Node JS
Nome de usuário do Power BI Não se aplica a. Aplica-se a.
Palavra-passe do Power BI Não se aplica a. Aplica-se a.

ID de Cliente

Gorjeta

Aplica-se a:Entidade de serviço.Utilizador mestreAplica-se a.

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. Procure por Registo de Aplicações e selecione no link Registo 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 do espaço de trabalho

Gorjeta

Aplica-se a:Entidade de serviço.Utilizador mestreAplica-se a.

Para obter o GUID do ID de 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/.

    Uma captura de ecrã a mostrar a ID do espaço de trabalho GUID na URL do serviço do Power BI

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.

Uma captura de tela mostrando como encontrar o ID do espaço de trabalho nas configurações de administrador.

ID do relatório

Gorjeta

Aplica-se a:Entidade de serviço.Utilizador mestreAplica-se a.

Para obter o GUID do 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.

    Uma captura de tela mostrando o GUID do ID do relatório no serviço Power B I U R L

Segredo do cliente

Gorjeta

Aplica-se a:Aplica-se a.Principal de serviço Não se aplica a.Usuário mestre

Para obter o segredo do cliente, siga estes passos:

  1. Faça logon no Microsoft Azure.

  2. Procure por Registo de Aplicações e selecione no link Registo 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 sair desta página, o segredo do cliente será oculto e não será possível recuperar o seu valor.

ID de Inquilino

Gorjeta

Aplica-se a:Aplica-se a.Principal de serviço Não se aplica a.Usuário mestre

Para obter o GUID de identificação do locatário, siga estas etapas:

  1. Faça logon no Microsoft Azure.

  2. Procure por Registo de Aplicações e selecione no link Registo 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 diretório (locatário).

Nome de utilizador e palavra-passe do Power BI

Gorjeta

Aplica-se a:Não se aplica a.Entidade de serviço principal Aplica-se a.Usuário mestre

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 do principal de serviço

Gorjeta

Aplica-se a:Aplica-se a.Principal de serviço Não se aplica a.Usuário mestre

Esta etapa só é relevante se estiveres a usar o método de autenticação do principal 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 uma aplicação Microsoft Entra possa aceder ao conteúdo e às APIs do Power BI, um administrador do Power BI precisa ativar o acesso do principal de serviço no portal de administração do Power BI. Se não for o administrador do seu locatário, peça ao administrador do locatário para ativar as definições de locatário para si.

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

    Uma captura de tela mostrando a opção do menu de configurações do administrador no menu de configurações do serviço Power B I.

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

  3. Expanda as entidades de serviço podem usar Fabric APIs e ative esta opção.

    Uma captura de tela mostrando como habilitar a opção de configurações do desenvolvedor, na opção de menu de configurações do locatário, no serviço Power B I.

Nota

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

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

Para permitir que a sua aplicação Microsoft Entra aceda a objetos como relatórios, dashboards e modelos semânticos no serviço Power BI, adicione o principal de serviço ou utilizador mestre como membro ou administrador ao seu espaço de trabalho.

  1. Faça login no Fabric.

  2. Desloque-se para a área de trabalho para a qual pretende ativar o acesso e selecione Gerir acesso.

    Captura de ecrã mostrando o botão de acesso ao espaço de trabalho no menu 'Mais' de um espaço de trabalho do Power BI.

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

    Nota

    Se estiver a usar uma entidade de serviço, o nome dela será o nome que deu à sua aplicação 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.

    Uma captura de tela mostrando a opção de download ZIP no GitHub de exemplos de desenvolvedor do Power B I

  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:

    • Núcleo do .NET
    • .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 solução de incorporação para a sua organização.

  2. Abra a pasta incorporar para os seus clientes.

  1. Abra o aplicativo de incorporação de exemplo para os seus clientes usando uma destas maneiras:

  2. Abra appsettings.json.

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

    Parâmetro Principal de serviço Utilizador principal
    AuthenticationMode Serviço Principal 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 O seu nome de utilizador mestre, veja nome de utilizador e palavra-passe do Power BI
    PbiPassword N/A A sua senha mestre do utilizador, consulte nome de utilizador e senha do Power BI
    ClientSecret O segredo do cliente Microsoft Entra ID N/A
    WorkspaceId O ID do espaço de trabalho com o relatório incorporado, consulte ID do espaço de trabalho O ID do espaço de trabalho com o 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 estiveres a usar o Visual Studio, seleciona IIS Express (executar).

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

Desenvolvendo seu aplicativo

Após configurar e executar a aplicação de exemplo de integração para clientes, pode começar a desenvolver a sua própria aplicação.

Experimente o playground de análises integradas do Power BI para começar a desenvolver e manter-se atualizado com todos os novos recursos e atualizações do Power BI Embedded.

Quando estiver pronto, revise os requisitos para a mudança para 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 usaste tokens de avaliação de incorporação gratuita para desenvolvimento, deves adquirir uma capacidade para 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.

Considerações e limitações

As seguintes limitações se aplicam ao modo Direct Lake:

  • Requer um token de inserção V2.
  • Se estiver a usar uma entidade de serviço, precisará de uma conexão de Identidade Fixa (Sem SSO).
  • Atualmente, definir uma entidade de serviço como o método de autenticação numa conexão de Identidade Fixa é a única opção suportada pela automação. Outros métodos são suportados manualmente através do portal.

Conteúdos relacionados

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