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

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

Para obter mais informações sobre o fluxo geral de automação e as APIs que o aplicativo usa, consulte Automatizar a configuração de uma instalação de aplicativo 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 em seu portal.

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

Nota

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

Pré-requisitos

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

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

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

Registar uma aplicação no Microsoft Entra ID

Crie uma entidade de serviço conforme descrito em 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.

Salve o ID do aplicativo (ClientID) e o segredo do aplicativo (ClientSecret) para etapas posteriores.

Você pode passar pela ferramenta de configuração de incorporação para começar rapidamente a criar um registro de aplicativo. Se estiver a utilizar a Ferramenta de Registo de Aplicações do Power BI, selecione a opção Incorporar para os seus clientes.

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

Preparação do aplicativo de modelo

Depois de criar seu aplicativo modelo e ele estiver pronto para instalação, salve 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 Definir as 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 são cadeias de caracteres que diferenciam maiúsculas de minúsculas. Eles 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.

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.

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 seu aplicativo de modelo. Esta amostra foi deliberadamente mantida simples para fins de demonstração. Ele permite que você use uma função do Azure e a Configuração do Aplicativo do Azure para implantar e usar facilmente a API de instalação automatizada para seus aplicativos de modelo.

Baixar Visual Studio (versão 2017 ou posterior)

Baixe o Visual Studio (versão 2017 ou posterior). Certifique-se de baixar o pacote NuGet mais recente.

Baixe o exemplo de instalação automatizada do Azure Functions

Baixe o exemplo de instalação automatizada do Azure Functions do GitHub para começar.

Configurar a configuração do aplicativo do Azure

Para executar este exemplo, você precisa configurar a configuração do aplicativo do Azure com os valores e as chaves, conforme descrito aqui. As chaves são a ID do aplicativo, o segredo do aplicativo e os valores AppId, PackageKey e OwnerId do aplicativo modelo. Consulte as seções a seguir para obter informações sobre como obter esses valores.

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

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

O arquivo Constants.cs é mostrado aqui.

Obter as propriedades do aplicativo de modelo

Preencha todas as propriedades relevantes do aplicativo de modelo conforme elas são definidas quando o aplicativo é criado. Essas propriedades são os valores AppId, PackageKey e OwnerId do aplicativo de modelo.

Para obter os valores anteriores, siga estes passos:

1. Inicie sessão no Power BI.

2. Vá para o espaço de trabalho original do aplicativo.

3. Abra o painel Gerenciamento de versão.

   

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

   

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

   

6. Este 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. Um exemplo de URL será semelhante ao que é mostrado aqui.

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

Obter o ID do aplicativo

Preencha as informações do applicationId com a ID do aplicativo do Azure. O valor applicationId é usado pelo aplicativo para se identificar para os usuários dos quais você está solicitando permissões.

Para obter o ID do aplicativo, siga estas etapas:

1. Inicie sessão no portal do Azure.

2. No painel esquerdo, selecione Todos os serviços>Registos de aplicações.

   

3. Selecione o aplicativo que precisa da ID do aplicativo.

   

4. Há uma ID de aplicativo listada como GUID. Use este ID do aplicativo como o valor applicationId para o aplicativo.

   

Obter o segredo da aplicação

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

Para obter o segredo do aplicativo, execute estas etapas:

1. Inicie sessão no portal do Azure.

2. No painel esquerdo, selecione Todos os serviços>Registos de aplicações.

   

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

   

4. Selecione Certificados e segredos em Gerenciar.

5. Selecione Novos segredos do cliente.

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

   

Teste a sua função localmente

Siga as etapas descritas em Executar a função localmente para executar sua função.

Configure seu portal para emitir uma POST solicitação 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 pares chave-valor. As chaves são nomes de parâmetros conforme definido no Power BI Desktop. Os valores são os valores desejados a serem definidos para cada parâmetro no aplicativo de modelo.

Nota

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

O fluxo desejado deve ser:

1. O portal prepara o pedido, por utilizador ou sessão.
2. A POST /api/install solicitação é 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 é o valor desejado a ser definido.
3. Se tudo estiver configurado corretamente, o navegador deverá redirecionar 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 dos parâmetros são definidos conforme configurado nas etapas 1 e 2.

Conteúdos relacionados

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 APIs de instalação automatizada de aplicativo de modelo em seu produto e começar a testá-lo em ambientes de produção.