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 na sua fonte de dados, e estão prontos para começar!

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 automaticamente para seus usuários.

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 de acesso exclusivo de aplicativo com base em um principal de serviço (token de acesso exclusivo de aplicativo) registrado 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 utilizador para o Power BI usando um POST método de redirecionamento, que contém o bilhete de instalação.

5. O utilizador é redirecionado para a sua conta no Power BI com o tíquete de instalação e é instruído a instalar a aplicação modelo. Quando o usuário seleciona Instalar, o aplicativo de modelo é instalado para ele.

Observação

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

• A sua própria configuração de tenant 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 apenas de aplicação) registrado 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 para criar aplicativos de modelo ou Criar um aplicativo de modelo no Power BI.
• Para poder testar o seu fluxo de trabalho de automação, adicione o principal do serviço ao espaço de trabalho da aplicação 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 seu ambiente de desenvolvimento de automação de aplicações de modelos

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 um principal de serviço conforme descrito em 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 no lado do servidor para criar um segredo de aplicação.

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

Adicione o principal de serviço ao espaço de trabalho da aplicação modelo como administrador, para testar o 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 de Gerenciamento de Versões da aplicação 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.

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.

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 de 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 a partir do URL de instalação
TemplateAppInstall:ServicePrincipal:ClientId	Principal do serviço ID da aplicação
TemplateAppInstall:ServicePrincipal:ClientSecret	Principal de serviço segredo do aplicativo

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 em 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=66667...9cccc0000&packageKey=b2df4b...dLpHIUnum2pr6k&ownerId=aaaa...22222&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. Entre no portal do Azure.

2. No menu do portal, selecione Todos os serviços.

3. Na página Todos os serviços, na seção Identidade , selecione >Registros de aplicativos.

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

   

5. 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. Entre no portal do Azure.

2. No menu do portal, selecione Todos os serviços.

3. Na página Todos os serviços, na seção Identidade , selecione >Registros de aplicativos.

   

4. Selecione Certificados e segredos em Gerenciar.

5. Selecione Novo segredo do cliente.

6. Insira um nome na caixa Descrição e selecione uma duração. Em seguida, selecione Adicionar para obter o valor do seu aplicativo, que você verá sob o título Valor do segredo do cliente.

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.

Observação

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