Configuração automatizada de uma instalação de aplicativo de modelo

Os aplicativos de modelo são uma ótima maneira de os clientes começarem a obter informações de seus dados. Os aplicativos de modelo os colocam em funcionamento rapidamente, conectando-os aos seus dados. Os aplicativos de modelo fornecem relatórios pré-criados que eles podem personalizar se assim desejarem.

Os clientes nem sempre estão familiarizados com os detalhes de como se conectar aos seus dados. Ter que fornecer esses detalhes quando eles instalam um aplicativo modelo pode ser um ponto problemático para eles.

Se você for um provedor de serviços de dados e tiver criado um aplicativo de modelo para ajudar seus clientes a começar a usar seus dados em seu serviço, você pode facilitar a instalação do aplicativo de modelo. Você pode automatizar a configuração dos parâmetros do seu aplicativo de modelo. Quando o cliente entra no seu portal, ele seleciona um link especial que você preparou. Este link:

• Lança a automação, que reúne as informações de que precisa.
• Pré-configura os parâmetros do aplicativo de modelo.
• Redireciona o cliente para sua conta do Power BI onde ele pode instalar o aplicativo.

Tudo o que eles precisam fazer é selecionar Instalar e autenticar em sua fonte de dados, e eles estão prontos para ir!

A experiência do cliente é ilustrada aqui.

Este artigo descreve o fluxo básico, os pré-requisitos e as principais etapas e APIs necessárias para automatizar a configuração de uma instalação de aplicativo de modelo. Se quiser mergulhar e começar, pule para o tutorial onde você automatiza a configuração da instalação do aplicativo de modelo usando um aplicativo de exemplo simples que preparamos e que usa uma função do Azure.

Fluxo básico

O fluxo básico de automatizar a configuração de uma instalação de aplicativo de modelo é o seguinte:

1. O usuário entra no portal do ISV e seleciona o link fornecido. Esta ação inicia o fluxo automatizado. O portal do ISV prepara a configuração específica do usuário nesta fase.

2. O ISV adquire um token somente de aplicativo com base em uma entidade de serviço (token somente de aplicativo) registrada no locatário do ISV.

3. Usando APIs REST do Power BI, o ISV cria um tíquete de instalação, que contém a configuração de parâmetro específica do usuário, conforme preparado pelo ISV.

4. O ISV redireciona o usuário para o Power BI usando um POST método de redirecionamento que contém o tíquete de instalação.

5. O usuário é redirecionado para sua conta do Power BI com o tíquete de instalação e é solicitado a instalar o aplicativo de modelo. Quando o usuário seleciona Instalar, o aplicativo de modelo é instalado para ele.

Pré-requisitos

Para fornecer uma experiência de instalação pré-configurada para seu aplicativo modelo, os seguintes pré-requisitos são necessários:

• Uma licença Pro do Power BI. Se não estiver inscrito no Power BI Pro, poderá inscrever-se numa avaliação gratuita antes de começar.

• Seu próprio locatário do Microsoft Entra configurado. Para obter instruções sobre como configurar um, consulte Criar um locatário do Microsoft Entra.

• Uma entidade de serviço (token somente aplicativo) registrada no locatário anterior. Para obter mais informações, consulte Incorporar conteúdo do Power BI com entidade de serviço e um segredo de aplicativo. Certifique-se de registrar o aplicativo como um aplicativo Web do lado do servidor. Você registra um aplicativo Web do lado do servidor para criar um segredo de aplicativo. A partir desse processo, você precisa salvar o ID do aplicativo (ClientID) e o segredo do aplicativo (ClientSecret) para etapas posteriores.

• Um aplicativo de modelo parametrizado pronto para instalação. O aplicativo de modelo deve ser criado no mesmo locatário no qual você registra seu aplicativo no Microsoft Entra ID. Para obter mais informações, consulte Dicas de aplicativo de modelo ou Criar um aplicativo de modelo no Power BI. No aplicativo modelo, você precisa observar as seguintes informações para as próximas etapas:

  • ID do aplicativo, Chave do pacote e ID do proprietário como aparecem na URL de instalação no final do processo de definição das propriedades do aplicativo modelo quando o aplicativo foi criado. Você também pode obter o mesmo link selecionando Obter link no painel Gerenciamento de Versões do aplicativo de modelo.
  • Nomes de parâmetros conforme definidos no modelo semântico do aplicativo de modelo. Os nomes dos parâmetros diferenciam maiúsculas de minúsculas e também podem ser recuperados na guia Configurações de Parâmetro quando você define as propriedades do aplicativo de modelo ou das configurações do modelo semântico no Power BI.

• Para poder testar seu fluxo de trabalho de automação, adicione a entidade de serviço ao espaço de trabalho do aplicativo de modelo como administrador.

  Nota

  Você pode testar seu aplicativo de instalação pré-configurado em seu aplicativo de modelo se o aplicativo de modelo estiver pronto para instalação, mesmo que ainda não esteja disponível publicamente no AppSource. Para que os utilizadores fora do seu inquilino possam utilizar a aplicação de instalação automatizada para instalar a sua aplicação de modelo, a aplicação de modelo tem de estar disponível publicamente no mercado de aplicações do Power BI. Antes de distribuir seu aplicativo modelo usando o aplicativo de instalação automatizada que você está criando, certifique-se de publicá-lo no Partner Center.

Principais etapas e APIs

As principais etapas para automatizar a configuração de uma instalação de aplicativo de modelo e as APIs necessárias são descritas nas seções a seguir. Embora a maioria das etapas seja feita com APIs REST do Power BI, os exemplos de código descritos aqui são feitos com o SDK do .NET.

Etapa 1: Criar um objeto de cliente do Power BI

Usar APIs REST do Power BI exige que você obtenha um token de acesso para sua entidade de serviço da ID do Microsoft Entra. É necessário obter um token de acesso do Microsoft Entra para seu aplicativo Power BI antes de fazer chamadas para as APIs REST do Power BI. Para criar o cliente do Power BI com seu token de acesso, você precisa criar seu objeto de cliente do Power BI, que permite interagir com as APIs REST do Power BI. Você cria o objeto de cliente do Power BI encapsulando o AccessToken com um objeto Microsoft.Rest.TokenCredentials.

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 goes here.
}

Etapa 2: Criar um tíquete de instalação

Crie um tíquete de instalação, que é usado quando você redireciona seus usuários para o Power BI. A API usada para esta operação é a API CreateInstallTicket .

• Aplicativos de modelo CreateInstallTicket

Um exemplo de como criar um tíquete de instalação para instalação e configuração do aplicativo de modelo está disponível no arquivo InstallTemplateApp/InstallAppFunction.cs no aplicativo de exemplo.

O exemplo de código a seguir mostra como usar o aplicativo de modelo CreateInstallTicket REST API.

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

// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
    InstallDetails = new List<TemplateAppInstallDetails>()
    {
        new TemplateAppInstallDetails()
        {
            AppId = Guid.Parse(AppId),
            PackageKey = PackageKey,
            OwnerTenantId = Guid.Parse(OwnerId),
            Config = new TemplateAppConfigurationRequest()
            {
                Configuration = Parameters
                                    .GroupBy(p => p.Name)
                                    .ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
            }
        }
    }
};

// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);

Etapa 3: Redirecionar usuários para o Power BI com o tíquete

Depois de criar um tíquete de instalação, use-o para redirecionar seus usuários para o Power BI para continuar com a instalação e a configuração do aplicativo de modelo. Você usa um redirecionamento de método para a URL de instalação do aplicativo de POST modelo, com o tíquete de instalação no corpo da solicitação.

Existem vários métodos documentados de como emitir um redirecionamento usando POST solicitações. Escolher um ou outro depende do cenário e de como seus usuários interagem com seu portal ou serviço.

Um exemplo simples, usado principalmente para fins de teste, usa um formulário com um campo oculto, que se envia automaticamente após o carregamento.

<html>
    <body onload='document.forms["form"].submit()'>
        <!-- form method is POST and action is the app install URL -->
        <form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
            <!-- value should be the new install ticket -->
            <input type='hidden' name='ticket' value='H4sI....AAA='>
        </form>
    </body>
</html>

O exemplo a seguir da resposta do aplicativo de exemplo mantém o tíquete de instalação e redireciona automaticamente os usuários para o Power BI. A resposta para essa função do Azure é o mesmo formulário de autoenvio automático que vemos no exemplo HTML anterior.

...
    return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}

...

public static string RedirectWithData(string url, string ticket)
{
    StringBuilder s = new StringBuilder();
    s.Append("<html>");
    s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
    s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
    s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
    s.Append("</form></body></html>");
    return s.ToString();
}

Etapa 4: Mover sua automação para a produção

Quando a automação projetada estiver pronta, certifique-se de movê-la para a produção.

Conteúdos relacionados

• Experimente nosso tutorial, que usa uma função simples do Azure para automatizar a configuração de uma instalação de aplicativo de modelo.
• Tem dúvidas? Tente perguntar à Comunidade do Power BI.