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 insights de seus dados. Os aplicativos de modelo os colocarão em funcionamento rapidamente conectando-os aos seus dados. Os aplicativos de modelo fornecem a eles relatórios predefinidos que podem ser personalizados se 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 de modelo pode ser um inconveniente 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ê poderá facilitar a instalação do aplicativo de modelo. Você pode automatizar a configuração dos parâmetros do aplicativo de modelo. Quando o cliente entra no portal, ele seleciona um link especial que você preparou. Este link:

• Inicia a automação, que coleta as informações necessárias.
• Pré-configura os parâmetros do aplicativo de modelo.
• Redireciona o cliente para sua conta do Power BI, na qual ele pode instalar o aplicativo.

Tudo o que eles precisam fazer é selecionar Instalar, autenticar em sua fonte de dados e pronto!

A experiência do cliente é ilustrada aqui.

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

Fluxo básico para configuração automatizada

O fluxo básico para automatizar a configuração de uma instalação de aplicativo de modelo prossegue da seguinte maneira:

1. O usuário entra no portal do ISV e seleciona o link fornecido. Essa ação inicia o fluxo automatizado. O portal do ISV prepara a configuração específica do usuário neste estágio.
2. O ISV adquire um token somente de aplicativo com base em uma entidade de serviço (token somente 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 de modelo, os seguintes pré-requisitos são necessários:

• Uma licença do Power BI Pro. Se você não estiver inscrito no Power BI Pro, inscreva-se para uma avaliação gratuita antes de começar.

• Sua própria configuração de locatário do Microsoft Entra. Para obter instruções sobre como configurar um, consulte Criar um locatário do Microsoft Entra.

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

• Um aplicativo de modelo parametrizado pronto para instalação. O modelo de aplicativo 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 Crie um aplicativo de modelo no Power BI. No aplicativo de modelo, você precisa observar as seguintes informações para as próximas etapas:

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

• Para poder testar o fluxo de trabalho de automação, adicione o principal de serviço ao espaço de trabalho do aplicativo modelo na função de administrador.

  Observação

  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 usuários fora do locatário possam usar o aplicativo de instalação automatizado para instalar seu aplicativo de modelo, o aplicativo de modelo deve estar disponível publicamente no AppSource. Antes de distribuir seu aplicativo de modelo usando o aplicativo de instalação automatizado que você está criando, publique-o 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 as APIs REST do Power BI, os exemplos de código aqui descritos são feitos com o SDK do .NET.

Etapa 1: Criar um objeto cliente do Power BI

O uso de APIs REST do Power BI exige que você obtenha um token de acesso para o seu principal de serviço do Microsoft Entra ID. Você precisa obter um token de acesso do Microsoft Entra para seu aplicativo do 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 cliente do Power BI, que permite interagir com as APIs REST do Power BI. Você cria o objeto 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 ticket 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 essa operação é a API CreateInstallTicket .

• Aplicativos de modelo – Criar tíquete de instalação

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 a API REST CreateInstallTicket do aplicativo de modelo.

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 ticket de instalação, você o usará para redirecionar seus usuários ao Power BI para continuar com a instalação e configuração do aplicativo modelo. Você usa um método de redirecionamento POST para a URL de instalação do aplicativo modelo, com o tíquete de instalação no corpo da solicitação.

Há 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 os 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 ao carregar.

<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 conté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 auto-envio 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 produção

Quando a automação que você projetou estiver pronta, lembre-se de movê-la para produção.

Conteúdo relacionado

• Experimente nosso tutorial, que usa uma função simples do Azure para automatizar a configuração de uma instalação de aplicativo de modelo.
• Mais perguntas? Tente perguntar na Comunidade do Power BI.