Ambiente da execução

A mesma automação testa em homologação e opera em produção. O que muda de um lugar para o outro (endereço do sistema, usuário, senha) fica no ambiente, cadastrado no Proton, e não repetido em cada dataset. O script pede o valor pelo nome e recebe o do ambiente em que a execução está rodando.

A execução fica com o ambiente escolhido no disparo (tela, agendamento, recorrência ou conector) ou, sem escolha, com o ambiente padrão do dataset. Sem os dois, ela roda sem ambiente.

Ler as variáveis

Python

from proton.proton_automation import start_component
from proton.proton_environment import get_environment_name, get_environment_value, is_production
from proton.proton_logs import set_log

start_component()  # já lê o ambiente da execução, uma vez

url = get_environment_value("SAP_URL")
usuario = get_environment_value("SAP_USUARIO")
senha = get_environment_value("SAP_SENHA")

set_log(f"Ambiente: {get_environment_name()}")
if is_production():
    set_log("Execução em produção: sem gravar documento de teste")

Função (proton.proton_environment)	O que faz
get_environment_value(nome, allow_empty=False)	Valor da variável; erro se ela não existe ou está vazia (allow_empty=True aceita "")
get_environment_variables()	Cópia de todas as variáveis; vazia sem ambiente ou fora do Proton
get_environment_name()	Nome do ambiente; None sem ambiente ou fora do Proton
is_production()	Se o ambiente tem a marca de produção
mask_environment_values(texto)	O texto com os valores do ambiente trocados por ••••••
load_environment(force=False)	Lê o ambiente; force=True lê de novo

Java

import br.com.atomicsolutions.proton.ProtonAutomation;
import br.com.atomicsolutions.proton.ProtonEnvironment;
import static br.com.atomicsolutions.proton.ProtonLogs.setLog;

ProtonAutomation.startComponent();  // já lê o ambiente da execução, uma vez

String url = ProtonEnvironment.get("SAP_URL");
String usuario = ProtonEnvironment.get("SAP_USUARIO");
String senha = ProtonEnvironment.get("SAP_SENHA");

setLog("Ambiente: " + ProtonEnvironment.getName());
if (ProtonEnvironment.isProduction()) {
    setLog("Execução em produção: sem gravar documento de teste");
}

Método (ProtonEnvironment)	O que faz
get(nome) e get(nome, allowEmpty)	Valor da variável; erro se ela não existe ou está vazia (allowEmpty = true aceita "")
getAll()	Todas as variáveis, somente leitura; vazio sem ambiente ou fora do Proton
getName()	Nome do ambiente; null sem ambiente ou fora do Proton
isProduction()	Se o ambiente tem a marca de produção
mask(texto)	O texto com os valores do ambiente trocados por ••••••
load() e reload()	Lê o ambiente uma vez; reload() lê de novo

Nos ambientes, use os mesmos nomes de variáveis (SISTEMA_URL em Homologação e em Produção): o script lê sempre o mesmo nome, e o ambiente decide o valor. Só o que muda de comportamento em produção usa a marca de produção. O nome é comparado exatamente, com maiúsculas e minúsculas.

Uma leitura por execução

A SDK pede o ambiente ao Proton uma vez por execução, no start_component() (Python) ou no startComponent() (Java), e guarda tudo em memória. Sem essa chamada, a leitura acontece no primeiro acesso ao ambiente. A execução inteira usa os mesmos valores, mesmo que alguém altere o ambiente no meio.

Os valores nunca vão para disco, para o log ou para as variáveis do processo. A saída da execução ganha só uma linha com o nome do ambiente e a quantidade de variáveis.

O Proton entrega o ambiente só enquanto a execução roda. A leitura usa o mesmo token e a mesma permissão das outras rotas da execução (Execuções: visualizar).

Erros

A leitura por nome nunca devolve vazio no lugar de um erro: ela para o script com ProtonEnvironmentError (Python) ou ProtonEnvironmentException (Java). A mensagem diz a variável e o ambiente, nunca o valor.

Motivo (reason)	Quando
environmentVariableNotFound	O ambiente não tem a variável
emptyVariable	A variável existe, mas está vazia
runWithoutEnvironment	A execução não tem ambiente: defina o ambiente padrão do dataset ou escolha um no disparo
notProtonExecution	Leitura por nome fora de uma execução do Proton
runAlreadyFinished	A execução já terminou
datasetRunNotFound	A execução não existe na organização do token
httpError	Sem acesso (HTTP 401 ou 403: confira o token e a permissão), outro status ou sem resposta

Uma falha na leitura feita ao abrir o passo não derruba o componente: a automação que não usa o ambiente segue normalmente, e o erro volta no primeiro acesso ao ambiente, inclusive no nome e na marca de produção. Assim, uma falha de rede não vira "não é produção".

Máscara nos logs

O Proton não diz à SDK quais variáveis são segredo, então ela mascara todos os valores do ambiente no que envia ao log da execução: cada valor vira ••••••, do mais longo para o mais curto.

• Valores com menos de 4 caracteres não são mascarados, senão o log fica ilegível. Não guarde segredo com menos de 4 caracteres.
• Os parâmetros de saída são gravados como vieram: são escritos de propósito.
• O que o script imprime por conta própria não passa pela SDK. Para isso, use mask_environment_values (Python) ou ProtonEnvironment.mask (Java).

Da categoria do dataset para o ambiente

No Proton 4, o script decidia endereço, usuário e senha pela categoria do dataset. No Proton 5 o dataset não tem categoria: as funções de categoria estão obsoletas e avisam no log. Leia os valores do ambiente:

Python

# Antes (Proton 4)
if get_dataset_category_name() == "PRD":
    url = "https://sistema.empresa.com.br"
else:
    url = "https://sistema-hml.empresa.com.br"

# Depois (Proton 5)
url = get_environment_value("SISTEMA_URL")

Java

// Antes (Proton 4)
String url = "PRD".equals(ProtonAutomation.getDatasetCategory()) ? URL_PRD : URL_HML;

// Depois (Proton 5)
String url = ProtonEnvironment.get("SISTEMA_URL");

Não compare o nome do ambiente com a antiga categoria: ele é texto livre ("Produção", "PRD", "Homologação 2"). Para o que muda de comportamento em produção, use a marca de produção.