Visão geral de variáveis de ambiente para o Power Platform

As variáveis de ambiente permitem o cenário básico de gerenciamento do ciclo de vida do aplicativo (ALM) de mover um aplicativo entre ambientes da Power Platform. Nesse cenário, o aplicativo permanece exatamente o mesmo, exceto por algumas referências de aplicativos externos importantes (como tabelas, conexões e chaves) que são diferentes entre o ambiente de origem e o ambiente de destino. O aplicativo exige que a estrutura das tabelas ou conexões seja exatamente a mesma entre os ambientes de origem e destino, com algumas diferenças. As variáveis de ambiente permitem especificar quais dessas diferentes referências externas devem ser atualizadas à medida que o aplicativo é movido entre os ambientes.

As variáveis de ambiente armazenam as chaves e os valores dos parâmetros, que servem como entrada para diversos outros objetos do aplicativo. Separar os parâmetros dos objetos de consumo permite alterar os valores dentro do mesmo ambiente ou ao migrar soluções para outros ambientes. A alternativa é deixar os valores dos parâmetros embutidos em código nos componentes que os utilizam. Geralmente, isso é problemático; especialmente quando os valores precisam ser alterados durante as operações de ALM. Como as variáveis de ambiente são componentes da solução, é possível transportar as referências (chaves) e alterar os valores quando as soluções são migradas para outros ambientes.

Benefícios de usar variáveis de ambiente:

• Fornecem novos valores de parâmetro ao importar soluções para outros ambientes.
• Armazenam a configuração das fontes de dados usadas em fluxos e aplicativos de tela. Por exemplo, o site do SharePoint Online e os parâmetros de lista podem ser armazenados como variáveis de ambiente; portanto, permitem que você se conecte a diferentes sites e listas em diferentes ambientes sem a necessidade de modificar os aplicativos e os fluxos.
• Empacotar e transportar sua personalização e sua configuração juntas e gerenciá-las em um único local.
• Empacotar e transportar segredos, como credenciais usadas por diferentes componentes, separadamente dos componentes que os usam.
• Uma variável de ambiente pode ser usada em muitos componentes da solução diferentes, sejam eles do mesmo tipo de componente ou diferentes. Por exemplo, um fluxo e um aplicativo de tela podem usar a mesma variável de ambiente. Quando o valor da variável de ambiente precisa ser alterado, só é necessário alterar um valor.
• Além disso, se precisar desativar uma fonte de dados em ambientes de produção, você poderá atualizar os valores das variáveis de ambiente com informações da nova fonte de dados. Os aplicativos e os fluxos não requerem modificação e começarão a usar a nova fonte de dados.
• Suportado pelas ferramentas SolutionPackager e DevOps permite a integração e entrega contínua (CI/CD).
• As variáveis de ambiente podem ser descompactadas e armazenadas no controle de origem. Talvez você também possa armazenar arquivos de valores de variáveis de ambiente diferentes para a configuração separada necessária em ambientes diferentes. O Pacote de Soluções poderá aceitar o arquivo correspondente ao ambiente para o qual a solução será importada.

Como a variável de ambiente funciona?

As variáveis de ambiente podem ser criadas e modificadas na interface de solução moderna e criadas automaticamente ao se conectar a determinadas fontes de dados em aplicativos de tela ou usando código. Elas também podem ser importadas para um ambiente por meio de soluções. Como há variáveis de ambiente presentes em um ambiente, elas podem ser usadas como entradas ao criar aplicativos de tela, fluxos do Power Automate ao desenvolver plugins e muitos outros locais, como adicionar um painel do Power BI a um aplicativo baseado em modelo. Quando esses tipos de objetos usam variáveis de ambiente, os valores são derivados das variáveis de ambiente e podem ser alterados quando as soluções são importadas para outros ambientes.

Criar uma variável de ambiente em uma solução

1. Entre no Power Apps (make.powerapps.com) e, no painel esquerdo, selecione Soluções. Se o item não estiver no painel lateral, selecione …Mais e selecione o item desejado.
2. Abra a solução desejada ou crie uma nova.
3. Na barra de comandos, selecione Novo>Mais e, em seguida, selecione Variável de ambiente.
4. No painel direito, preencha as seguintes colunas e selecione Salvar:

   • Nome para exibição. Insira um nome para a variável do ambiente.

   • Nome.. O nome exclusivo é gerado automaticamente do Nome de exibição, mas você pode alterá-lo.

   • Tipo de Dados. Selecione Número decimal, Texto, JSON, Duas opções, Fonte de dados ou Segredo.

     Observação

     • Se Fonte de dados for o tipo selecionado, também será necessário selecionar o conector, uma conexão válida para o conector selecionado e o tipo de parâmetro. No entanto, a conexão não é armazenada como parte da variável de ambiente. A conexão é usada apenas para recuperar valores de parâmetros disponíveis, como os sites do SharePoint aos quais você tem acesso ou as listas associadas a um site. Para determinados parâmetros, como listas do SharePoint, também será necessário selecionar uma variável de ambiente de fonte de dados pai, como o site do SharePoint. Depois de salvos, eles serão relacionados no banco de dados.
     • Se Segredo for o tipo selecionado, serão necessárias informações adicionais para configurar o Azure Key Vault para permitir ao Power Platform acessar o segredo.

   • Current Value. Também conhecido como valor. Esta propriedade é opcional e faz parte da tabela de valores de variáveis de ambiente. Quando existir um valor, ele será usado, mesmo se um valor padrão também estiver presente. Remova o valor da sua solução se não quiser usá-lo no próximo ambiente. Os valores também são separados em arquivos JSON separados no arquivo solution.zip exportado e podem ser editados offline. Mais Informações: Como faço para remover um valor de uma variável de ambiente?

   • Valor Padrão. Essa coluna faz parte da tabela de definição da variável de ambiente e não é obrigatória. O valor padrão é usado se não houver um valor atual.

     A separação do valor padrão e do valor atual permite que você atenda à definição e ao valor padrão de forma separada do valor. Por exemplo, um fornecedor de aplicativo pode listar a oferta no AppSource com um valor padrão. Opcionalmente, o cliente pode fornecer um novo valor. Quando o fornecedor do aplicativo publica atualizações no aplicativo, o valor definido pelo cliente não é substituído.

     

     Observação

     O valor não pode existir sem uma definição. A interface permite apenas a criação de um valor por definição.

Insira novos valores ao importar soluções

A interface de importação de solução moderna inclui a capacidade de inserir valores para variáveis de ambiente. Isso define a propriedade de valor na tabela environmentvariablevalue.

A partir de uma atualização em 7 de dezembro de 2023, todos os valores da variável de ambiente permanecem visíveis durante a importação de soluções (ou durante o uso de Pipelines para implantar). As variáveis de ambiente sem um valor ou valor padrão deverão apresentar um valor, mas aquelas que, de outra forma, forem preenchidas com um rótulo abaixo da área de texto indicando a origem do valor: valor da solução, valor do ambiente de destino ou valor padrão.

Notificações

Uma notificação será exibida quando as variáveis de ambiente não possuírem nenhum valor. Este é um lembrete para definir os valores para que os componentes dependentes das variáveis de ambiente não falhem.

Segurança

A tabela environmentvariabledefinition é de propriedade do usuário ou da equipe. Ao criar um aplicativo que usa variáveis de ambiente, certifique-se de atribuir aos usuários o nível apropriado de privilégio para a tabela em questão. A permissão para a tabela environmentvariablevalue é herdada da tabela pai environmentvariabledefinition e, portanto, não requer privilégios separados. Os privilégios para as tabelas environmentvariabledefinition estão incluídos nos direitos de acesso Criador de Ambiente e Usuário Básico por padrão. Mais informações: Segurança no Dataverse.

Nomenclatura

Garanta que os nomes das variáveis de ambiente sejam exclusivos para que possam ser referenciados com precisão. Nomes de exibição de variáveis de ambiente duplicados tornam as variáveis de ambiente difíceis de diferenciar e usar. Certifique-se de que os nomes das variáveis de ambiente sejam exclusivos para que possam ser referenciados com precisão. Os nomes $authentication e $authentication são parâmetros especialmente reservados para fluxos e devem ser evitados. A gravação de fluxo será bloqueada, se variáveis de ambiente com esses nomes forem usadas. Se uma variável de ambiente for usada em um fluxo e o nome de exibição da variável de ambiente for alterado, o designer mostrará os tokens do nome de exibição novos e anteriores para ajudar na identificação. Ao atualizar o fluxo, é recomendável que você remova a referência da variável de ambiente e adicione-a novamente.

Limitações atuais

• A validação dos valores das variáveis de ambiente acontece nas interfaces do usuário e nos componentes que as utilizam, mas não no Dataverse. Portanto, certifique-se de que os valores adequados sejam definidos se estiverem sendo modificados por meio do código.
• As tarefas do Power Platform Build Tools ainda não estão disponíveis para gerenciar variáveis de ambiente de fonte de dados. No entanto, isso não bloqueia o uso nas ferramentas fornecidas pela Microsoft nem nos sistemas de controle do código-fonte.
• Interagir com variáveis de ambiente por meio de código personalizado requer uma chamada à API para buscar os valores. Não há um cache exposto para código não Microsoft para uso.
• Para usar variáveis de ambiente com êxito com listas do SharePoint, o nome de exibição e o nome lógico de cada coluna correspondente nos ambientes de origem e de destino deverão corresponder.
• As variáveis de ambiente são limitadas a um máximo de 2.000 caracteres.

Perguntas frequentes

Por que não consigo ver o valor de minha variável de ambiente?

Se a variável de ambiente estiver em solução gerenciada, você não conseguirá ver o valor, a menos que olhe dentro da Solução padrão. Esse comportamento ocorre por design, pois o valor da variável de ambiente é uma personalização não gerenciada.

Como posso ver onde as variáveis de ambiente estão sendo usadas?

Por meio da seleção de Mostrar dependências na interface da solução, durante a criação de componentes ou no controle de origem e no arquivo de solução ao visualizar o aplicativo ou os metadados de fluxo.

As variáveis de ambiente da fonte de dados são iguais às conexões?

Não. Embora elas estejam relacionadas, uma conexão representa uma credencial ou uma autenticação necessária para interagir com o conector. As variáveis de ambiente da fonte de dados armazenam parâmetros que são exigidos por uma ou mais ações no conector, e esses parâmetros geralmente variam dependendo da ação. Por exemplo, uma conexão do SharePoint Online não armazena nenhuma informação sobre sites, listas ou bibliotecas de documentos. Por isso, chamar o conector exige uma conexão válida e alguns parâmetros adicionais.

As variáveis de ambiente da fonte de dados podem ser usadas com conexões compartilhadas como SQL Server com autenticação SQL?

Geralmente, não. As conexões compartilhadas com o SQL Server armazenam os parâmetros necessários para se conectar aos dados dentro da conexão. Por exemplo, o nome do servidor e do banco de dados são fornecidos ao criar a conexão e, portanto, são sempre derivados da conexão.

As variáveis de ambiente da fonte de dados são usadas para conectores que dependem de autenticação baseada no usuário, como a ID do Microsoft Entra, porque os parâmetros não podem derivar da conexão. Por esses motivos, a autenticação com o SQL Server, que é uma conexão compartilhada, não usará as variáveis de ambiente da fonte de dados.

Meu pipeline automatizado do ALM pode usar arquivos de valores diferentes para ambientes diferentes?

Sim. O pacote de soluções aceita o nome do arquivo como parâmetros de entrada para que o pipeline possa empacotar um arquivo de valores diferentes na solução, dependendo do tipo de ambiente em que está sendo executado.

Devo incluir o valor na minha solução?

Não. As variáveis de ambiente devem ser usadas por aplicativos que precisam ter valores diferentes em diferentes ambientes onde a solução é implantada. As definições de variável de ambiente devem ser incluídas em sua solução, mas os valores devem ser fornecidos para o ambiente de destino durante a implantação. Esse comportamento resulta na definição da variável de ambiente sendo um objeto de solução gerenciado no ambiente de destino, enquanto a variável de ambiente é um registro não gerenciado.

Por que não consigo excluir um valor no meu ambiente?

Se o valor foi incluído em uma solução gerenciada, a única maneira de excluí-lo é atualizar a solução no ambiente de origem para excluir o valor e, em seguida, exportar uma nova versão da solução. Essa nova versão, então, pode ser importada para o ambiente usando uma operação de atualização (não uma atualização), resultando na exclusão do registro de valor.

E se alguém excluir um valor inadvertidamente?

Se ainda não foi evitado pelo sistema de dependência, o runtime usará o último valor conhecido como fallback.

Se um valor for alterado, quando o novo valor será usado em aplicativos de tela e fluxos da nuvem?

Pode levar até uma hora para publicar totalmente as variáveis de ambiente atualizadas porque o valor é enviado por push para os aplicativos e flui de forma assíncrona.

Licenças premium são necessárias?

Não. Embora o ALM exija o Dataverse (ou os aplicativos do Dynamics 365), o uso de conectores premium não é necessário. A única ressalva é se você está usando o conector do Dataverse para interagir com variáveis de ambiente como faria com outros registros de dados, como contas ou contatos. Anteriormente, essa era a única maneira de usar variáveis de ambiente em fluxos e aplicativos de tela.

Existe um limite para o número de variáveis de ambiente que posso ter?

Não. No entanto, o tamanho máximo de uma solução é 95 MB. Mais informações: Criar uma solução

Os nomes e as descrições de exibição de variáveis de ambiente podem ser localizados?

Sim.

Devo usar variáveis de ambiente em vez de armazenar dados de configuração em tabelas personalizadas?

Sim, se seus dados de configuração não forem relacionais. As variáveis de ambiente devem ser usadas para pares de chave/valor e quando o valor provavelmente precisar ser diferente em outros ambientes. Outras ferramentas, como o utilitário de migração de configuração, são mais adequadas para a migração de dados de configuração relacionais armazenados em tabelas personalizadas. Diferentemente de outros dados de configuração, as variáveis de ambiente são migradas dentro das soluções e, portanto, são muito mais simples de gerenciar e mais eficientes para importar.

Por que minha conexão não é salva para variáveis de ambiente da fonte de dados?

As conexões são usadas apenas para gerar a interface do usuário. Por exemplo, para recuperar nomes amigáveis para listas do SharePoint associadas a um site. Ao editar uma variável de ambiente de fonte de dados, certifique-se de selecionar uma conexão com acesso à fonte de dados. Se você não tiver mais acesso à conexão, poderá inserir manualmente um valor. Por exemplo, insira a URL do site do SharePoint ou o identificador exclusivo (GUID) de uma lista.

Quando há várias conexões disponíveis para uma única variável de ambiente (tipo de fonte de dados), há uma implementação por design para selecionar a primeira conexão na lista de conexões. Como geralmente há apenas uma conexão associada a uma variável de ambiente, isso não é algo que geralmente precisa ser validado. Além disso, com as alterações recentes na visibilidade do valor da variável de ambiente, isso é mais fácil de validar na importação.

Como removo um valor de uma variável de ambiente?

Você pode querer remover o valor de uma variável de ambiente de sua solução antes de exportar a solução. Assim, o valor existente permanece no ambiente de desenvolvimento, mas não é exportado na solução. Essa abordagem permite que um novo valor seja fornecido ao importar a solução para outro ambiente.

Para remover o valor, siga estas etapas:

1. Na solução em que a variável de ambiente está localizada, selecione a variável de ambiente para exibir as propriedades.

2. Em Valor Atual, selecione ...>Remover desta solução.

   

Posso usar variáveis de ambiente em conectores personalizados?

Sim. Suporte a variáveis de ambiente em conectores personalizados

Confira também

Usar variáveis de ambiente de fonte de dados em aplicativos de tela
Usar variáveis de ambiente em fluxos da nuvem de solução do Power Automate
Referência da tabela/entrada EnvironmentVariableDefinition
Exemplos de API Web
Usar variáveis de ambiente de fonte de dados em aplicativos de tela
Usar variáveis de ambiente nos fluxos da nuvem de solução do Power Automate
Usar segredos do Azure Key Vault
Suporte a variáveis de ambiente em conectores personalizados
Power Apps Blog: Variáveis de ambiente disponíveis em versão preliminar!