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 essa abordagem é problemática, especialmente quando os valores precisam ser alterados durante as operações de gerenciamento do ciclo de vida do aplicativo (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, os parâmetros de lista e site online do SharePoint podem ser armazenados como variáveis de ambiente. Essa abordagem permite que você se conecte a diferentes sites e listas em diferentes ambientes sem precisar modificar os aplicativos e 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 dentro da interface da solução moderna. Eles também podem ser criados automaticamente ao se conectar a determinadas fontes de dados em aplicativos tela ou com código. Elas também podem ser importadas para um ambiente por meio de soluções. As variáveis de ambiente podem ser usadas como entradas ao criar aplicativos de tela, fluxos do Power Automate, plug-ins e adicionar painéis a aplicativos baseados em modelo do Power BI. Quando você usa 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 manualmente 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 a 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. A conexão não é armazenada como parte da variável de ambiente. A variável de ambiente armazena informações, que não estão na conexão, necessárias para conectar o Power Apps ao servidor e à tabela corretos. 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.

     • 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. Um valor definido é usado mesmo se também existir um valor padrão. 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.

O Power Apps pode criar automaticamente variáveis de ambiente

Na guia Geral das configurações do Power Apps:

• Ativa a opção Criar variáveis de ambiente automaticamente ao adicionar fontes de dados. Agora, quando você adiciona uma nova fonte de dados ao seu aplicativo, ela adiciona uma variável de ambiente para você.

  

Fontes de dados diferentes

Diferentes fontes de dados permitem diferentes tipos de variáveis de ambiente.

Microsoft Dataverse

O Power Apps conecta-se nativamente ao Dataverse. Você não precisa de uma variável de ambiente para tabelas em seu ambiente atual. Quando você se conecta ao Dataverse, seu aplicativo procura automaticamente exatamente o mesmo nome de tabela em qualquer ambiente para o qual você o transporta. Contanto que a estrutura do nome da tabela seja a mesma no ambiente de destino que no ambiente original, ele funciona.

Se você usar uma tabela externa de um ambiente diferente (via Alterar Ambiente), então o Power Apps assume que deseja sempre fazer referência à mesma tabela. Você precisa de uma variável de ambiente se precisar que essa tabela externa seja uma tabela externa diferente ao passar de desenvolvimento para teste ou produção. É mais fácil permitir que o Power Apps cria automaticamente a variável de ambiente para você. (Se você adicionou a tabela ao seu aplicativo anteriormente, ative a opção de configurações, solte a tabela externa e adicione-a novamente.)

Ao adicionar a tabela externa ao aplicativo, escolha a guia Avançado para selecionar a variável de ambiente.

SharePoint

O SharePoint suporta somente conexões do Microsoft Entra. Assim, para o SharePoint, além de uma conexão válida, é necessária uma variável de ambiente separada para Site e Lista.

Para usar com êxito variáveis de ambiente com listas do SharePoint:

• O nome para exibição e o nome lógico de cada coluna correspondente nos ambientes de origem e de destino devem corresponder.
• As variáveis de ambiente para SharePoint devem ter metadados correspondentes. O SharePoint tem identificadores internos que podem não corresponder entre os ambientes de destino. Por exemplo, se você criar uma lista com o mesmo nome e colunas em um ambiente de destino, os nomes internos não corresponderão. Os metadados sempre correspondem se você duplicar um site do SharePoint e copiá-lo para o ambiente de destino.

SQL Server

SQL Server suporta muitos tipos diferentes de autenticação e conexões. Use variáveis de ambiente para conexões do Microsoft Entra. Uma variável de ambiente separada é necessária para o servidor e o banco de dados. O aplicativo é vinculado a nomes de tabela específicos assumindo-se que eles são os mesmos em diferentes ambientes.

Não use variáveis de ambiente para conexões compartilhadas, como Autenticação SQL básica com o SQL Server. Use referências de conexão para informações que são tradicionalmente passadas como parte da cadeia de conexão. Os parâmetros básicos de autenticação SQL fazem parte da cadeia de 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 com autenticação como Microsoft Entra. Nesses tipos de conexões, o Power Apps só tem um usuário identificado. O Power Apps não pode deduzir com qual serviço ou tabela você pretende trabalhar a partir da conexã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.

Os valores das variáveis de ambiente ficam visíveis ao importar soluções ou ao usar Pipelines para implantar. Variáveis de ambiente sem um valor padrão ou que exijam um valor são 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.

Observação

• Em alguns casos, para valores de variável de ambiente de fonte de dados específicos, um aviso de Acesso negado pode ser exibido se o criador importador não tiver acesso à conexão ou à fonte usada para a variável de ambiente. Esse é um aviso sem bloqueio, mas algo a ser observado dependendo de como você planeja usar a variável de ambiente no ambiente de destino.
• Você pode remover o valor de sua solução antes de exportá-la. Isso garante que o valor existente permanece em seu ambiente de desenvolvimento, mas não será exportado na solução. Essa abordagem permite que um novo valor seja fornecido ao importar a solução para outros ambientes. Mais Informações: Como faço para remover um valor de uma variável de ambiente?

Notificações

Uma notificação será exibida quando as variáveis de ambiente não possuírem nenhum valor. Defina 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.
• 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. Portanto, chamar o conector requer uma conexão válida e mais alguns parâmetros.

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!