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 na sua fonte de dados, e já está tudo 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 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 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. 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 utilizador é redirecionado para a sua conta do Power BI com o tíquete de instalação e é solicitado a instalar a aplicação 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 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.

• Um principal de serviço (token de aplicação apenas) registado no inquilino anterior. Para obter mais informações, consulte Incorporar conteúdo do Power BI com principal de serviço e um segredo de aplicação. Certifique-se de registrar o aplicativo como um aplicativo Web do lado do servidor . Você regista uma aplicação web do lado do servidor para criar um secreto de aplicação. 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 o seu fluxo de trabalho de automação, adicione o serviço principal ao espaço de trabalho da aplicação modelo como um 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 seu locatário possam usar o aplicativo de instalação automatizada para instalar seu aplicativo de modelo, o aplicativo de modelo deve estar disponível publicamente no AppSource. 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

Para utilizar as APIs REST do Power BI, é necessário obter um token de acesso para o seu principal de serviço a partir do Microsoft Entra ID. É 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 bilhete 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 .

• Aplicações de modelo - Criar ticket 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 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 utilizadores para o Power BI com o bilhete

Depois de criar um ticket de instalação, use-o para redirecionar os seus utilizadores para o Power BI para continuar com a instalação e configuração da aplicação de modelo. Você usa um redirecionamento do método POST para a URL de instalação da aplicação de 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ú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 à Comunidade do Power BI.