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

  • Artigo

Os aplicativos de modelo são uma ótima forma de os clientes começarem a obter insights dos dados deles. Os aplicativos de modelo os ativam e executam rapidamente conectando-os aos dados. Os aplicativos de modelo fornecem a eles relatórios predefinidos que eles podem personalizar, se quiserem.

Os clientes nem sempre estão familiarizados com os detalhes de como se conectar aos dados deles. Ter que fornecer esses detalhes ao instalar um aplicativo de 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 os clientes a começarem a usar os dados deles no serviço que você fornece, poderá facilitar a instalação do aplicativo para eles. 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 reúne as informações necessárias.
  • Pré-configura os parâmetros do aplicativo de modelo.
  • Redireciona o cliente para a conta do Power BI, onde ele pode instalar o aplicativo.

Tudo o que o cliente precisa fazer é selecionar Instalar e fazer a autenticação na fonte de dados dele.

A experiência do cliente está ilustrada aqui.

Illustration of user experience with an auto-installation application.

Este artigo descreve o fluxo básico, os pré-requisitos e as principais etapas e as APIs necessárias para automatizar a configuração de uma instalação do aplicativo de modelo. Se já quiser se aprofundar e começar a usar, você poderá pular direto para o tutorial, em que você 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

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

  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 baseado em uma entidade de serviço (token somente de aplicativo), que está registrada no locatário do ISV.

  3. Usando as 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 ao Power BI usando um método de redirecionamento POST, que contém o tíquete de instalação.

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

Observação

Embora os valores de parâmetro sejam configurados pelo ISV no processo da criação do tíquete de instalação, as credenciais relacionadas à fonte de dados são fornecidas apenas pelo usuário nos estágios finais da instalação. Essa organização impede que eles sejam expostos a terceiros e garante uma conexão segura entre o usuário e as fontes de dados do aplicativo de modelo.

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.

  • Seu próprio locatário do Microsoft Entra foi configurado. Para obter instruções sobre como configurar, confira 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, confira Inserir conteúdo do Power BI com a entidade de serviço e um 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 com parâmetros pronto para instalação. O aplicativo de modelo precisa ser criado no mesmo locatário em que você registra o aplicativo no Microsoft Entra ID. Para obter mais informações, confira dicas do aplicativo de modelo ou Criar um aplicativo de modelo no Power BI. No aplicativo de modelo, você precisa anotar as seguintes informações para as próximas etapas:

    • ID do Aplicativo, Chave do Pacote e ID do Proprietário conforme elas aparecem na URL de instalação ao 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 Release Management do aplicativo de modelo.
    • Os nomes de parâmetro conforme são 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ê definir 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 a entidade de serviço ao workspace do aplicativo de modelo como um Administrador.

    Observação

    Você poderá testar seu aplicativo de instalação pré-configurado no aplicativo de modelo se o aplicativo de modelo estiver pronto para instalação, mesmo que ele ainda não esteja disponível publicamente no AppSource. Para que os usuários fora do seu locatário possam usar o aplicativo de instalação automatizada a fim de instalar o aplicativo de modelo, o aplicativo de modelo precisa estar publicamente disponível no marketplace de aplicativos do Power BI. Antes de distribuir o aplicativo de modelo usando o aplicativo de instalação automatizada que você está criando, não se esqueça 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 as 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

O uso das APIs REST do Power BI exige que você obtenha um token de acesso para a entidade de serviço do Microsoft Entra ID. É necessário obter um token de acesso do Microsoft Entra para o seu aplicativo do Power BI antes de fazer chamadas a APIs REST do Power BI. Para criar o cliente do Power BI com o token de acesso, é necessário criar o objeto cliente do Power BI, que lhe permite interagir com as APIs REST do Power BI. Crie o objeto do 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 os usuários ao Power BI. A API usada para essa operação é a API CreateInstallTicket.

Um exemplo de como criar um tíquete de instalação para a instalação e a 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 ao Power BI com o tíquete

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

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

Um exemplo simples, empregado 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 ao Power BI. A resposta para essa Função do Azure é a mesma forma de autoenvio automático que vimos 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();
}

Observação

Há vários métodos de uso dos redirecionamentos de navegador POST. Você deve sempre usar o método mais seguro, que depende das suas necessidades e restrições de serviço. Lembre-se de que algumas formas de redirecionamento inseguro podem resultar na exposição de seus usuários ou do seu serviço a problemas de segurança.

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

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

Conteúdo relacionado