Tutorial: Automatizar a configuração da instalação do aplicativo de modelo usando uma função do Azure

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 aos clientes 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.

Neste tutorial, você usará um exemplo de instalação automatizada do Azure Functions que criamos para pré-configurar e instalar o aplicativo de modelo. Este exemplo foi deliberadamente simplificado para fins de demonstração. Ele encapsula a configuração de uma função do Azure para utilizar APIs do Power BI a fim de instalar um aplicativo de modelo e configurá-lo para os usuários automaticamente.

Para obter mais informações sobre o fluxo de automação geral e as APIs que o aplicativo usa, confira Automatizar a configuração da instalação de um aplicativo de modelo.

Nosso aplicativo simples usa uma função do Azure. Para obter mais informações sobre o Azure Functions, consulte a Documentação do Azure Functions.

Fluxo básico

O fluxo básico a seguir lista o que o aplicativo faz quando o cliente o inicia selecionando o link do portal.

1. O usuário entra no portal do ISV e seleciona o link fornecido. Essa ação inicia o fluxo. 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

• 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.
• 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.
• 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.
• 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.

Configurar o ambiente de desenvolvimento de automação de aplicativos de modelo

Antes de continuar configurando seu aplicativo, siga as instruções em Início Rápido: Criar um aplicativo de funções do Azure Functions com a Configuração de Aplicativos do Azure para desenvolver uma função do Azure junto com uma configuração de aplicativos do Azure. Crie a configuração de aplicativos conforme descrito no artigo.

Registre um aplicativo no Microsoft Entra ID

Crie uma entidade de serviço conforme descrito em Inserir conteúdo do Power BI com a entidade de serviço e um segredo do 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.

Salve a ID do Aplicativo (ClientID) e o Segredo do aplicativo (ClientSecret) para etapas posteriores.

É possível acessar a Ferramenta de configuração de inserção para começar a criar rapidamente um registro de aplicativo. Se você estiver usando a Ferramenta de Registro de Aplicativo do Power BI, selecione a opção Inserir para seus clientes.

Adicione a entidade de serviço ao workspace do aplicativo de modelo como um Administrador, para que você possa testar o fluxo de trabalho de automação.

Preparação do aplicativo de modelo

Depois que você criar o aplicativo de modelo e ele estiver pronto para a instalação, salve 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 Definir as propriedades do aplicativo de modelo quando o aplicativo foi criado.

  Você também pode obter o mesmo link selecionando Obter link no painel de 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 são cadeia de caracteres que diferenciam maiúsculas de minúsculas. Eles 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 conjunto de dados no Power BI.

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.

Instalar e configurar seu aplicativo de modelo

Nesta seção, você usará um exemplo de instalação automatizada do Azure Functions que criamos para pré-configurar e instalar o aplicativo de modelo. Este exemplo foi deliberadamente simplificado para fins de demonstração. Isso permite que você utilize uma função do Azure e a Configuração de Aplicativos do Azure para implantar e usar facilmente a API de instalação automatizada para aplicativos de modelo.

Baixe o Visual Studio (versão 2017 ou posterior)

Baixe o Visual Studio (versão 2017 ou posterior). Baixe a versão mais recente do pacote do NuGet.

Baixar o exemplo de Instalação Automatizada do Azure Functions

Baixe o exemplo de Instalação Automatizada do Azure Functions do GitHub para começar.

Definir a Configuração de Aplicativos do Azure

Para executar este exemplo, você precisa configurar sua Configuração de Aplicativos do Azure com os valores e as chaves descritas aqui. As chaves são a ID do Aplicativo, o Segredo do aplicativo e os valores AppId, PackageKey e OwnerId do aplicativo de modelo. Confira as seções a seguir para informações sobre como obter esses valores.

As chaves também são definidas no arquivo Constants.cs.

Chave de configuração	Significado
TemplateAppInstall:Application:AppId	AppId da URL de instalação
TemplateAppInstall:Application:PackageKey	PackageKey da URL de instalação
TemplateAppInstall:Application:OwnerId	OwnerId da URL de instalação
TemplateAppInstall:ServicePrincipal:ClientId	ID do Aplicativo da entidade de serviço
TemplateAppInstall:ServicePrincipal:ClientSecret	Segredo do aplicativo da entidade de serviço

O arquivo Constants.cs é mostrado aqui.

Obter as propriedades do aplicativo de modelo

Preencha todas as propriedades do aplicativo de modelo relevantes da forma como são definidas quando o aplicativo é criado. Essas propriedades são os valores AppId, PakcageKey e OwnerId do aplicativo de modelo.

Para obter os valores anteriores, siga estas etapas:

1. Entre no Power BI.

2. Acesse o workspace original do aplicativo.

3. Abra o painel Release Management.

   

4. Selecione a versão do aplicativo e receba o link de instalação dele.

   

5. Copie o link para a área de transferência.

   

6. Essa URL de instalação contém os três parâmetros de URL cujos valores você precisa. Use os valores appId, packageKey e ownerId para o aplicativo. Uma URL de exemplo será semelhante à mostrada aqui.

   https://app.powerbi.com/Redirect?action=InstallApp&appId=3c386...16bf71c67&packageKey=b2df4b...dLpHIUnum2pr6k&ownerId=72f9...1db47&buildVersion=5
   

Obtenha a ID do aplicativo

Preencha as informações de applicationId com a ID do aplicativo do Azure. A applicationId é usada pelo aplicativo a fim de se identificar aos usuários aos quais você está solicitando permissões.

Para obter a ID do aplicativo, siga estas etapas:

1. Entre no portal do Azure.

2. No painel à esquerda, selecione Todos os serviços>Registros de aplicativo.

   

3. Selecione o aplicativo que precisa usar a ID do aplicativo.

   

4. Há uma ID do Aplicativo listada como GUID. Use essa ID do aplicativo como a applicationId do aplicativo.

   

Obtenha o segredo do aplicativo

Preencha as informações de ApplicationSecret da seção Chaves na seção Registros de aplicativo do Azure. Esse atributo funciona quando você usa a entidade de serviço.

Para obter o segredo do aplicativo, siga estas etapas:

1. Entre no portal do Azure.

2. No painel à esquerda, selecione Todos os serviços>Registros de aplicativo.

   

3. Selecione o aplicativo que precisa usar o segredo do aplicativo.

   

4. Selecione Certificados e segredos em Gerenciar.

5. Selecione Segredos do novo cliente.

6. Insira um nome na caixa Descrição e selecione uma duração. Em seguida, selecione Salvar para obter o Valor do aplicativo. Quando você fecha o painel Chaves depois de salvar o valor da chave, o campo Valor é mostrado como oculto. Neste ponto, você não pode recuperar o valor da chave. Se você perder o valor da chave, crie uma nova no portal do Azure.

   

Testar sua função localmente

Siga as etapas conforme descrito em Executar a função localmente para executar a função.

Configure seu portal para emitir uma solicitação POST para a URL da função. Um exemplo é POST http://localhost:7071/api/install. O corpo da solicitação deve ser um objeto JSON que descreve os pares chave-valor. As chaves são nomes de parâmetro conforme definido em Power BI Desktop. Os valores são aqueles desejados a serem definidos para cada parâmetro no aplicativo de modelo.

Observação

Na produção, os valores de parâmetro são deduzidos para cada usuário pela lógica pretendida do portal.

O fluxo desejado deve ser:

1. O portal prepara a solicitação, de acordo com usuário e a sessão.
2. A solicitação POST /api/install é emitida para sua função do Azure. O corpo da solicitação consiste em pares chave-valor. A chave é o nome do parâmetro. O valor é aquele desejado a ser definido.
3. Se tudo estiver configurado corretamente, o navegador deverá ser redirecionado automaticamente para a conta do Power BI do cliente e mostrar o fluxo de instalação automatizada.
4. Após a instalação, os valores de parâmetro são definidos conforme configurado nas etapas 1 e 2.

Conteúdo relacionado

Publicar seu projeto no Azure

Para publicar seu projeto no Azure, siga as instruções na documentação do Azure Functions. Em seguida, você pode integrar as APIs de instalação automatizada do aplicativo de modelo ao produto e começar a testá-las em ambientes de produção.