Pular para conteúdo

Configuração

A ordem de precedência

Para quase tudo, a ordem é:

argumento do construtor  >  {INSTANCE_NAME}_VARIAVEL  >  VARIAVEL

O prefixo é o instance_name em maiúsculas. Com instance_name='producao', a variável específica é PRODUCAO_CACHE_DURATION e a genérica é CACHE_DURATION.

Duas variáveis invertem essa ordem

TIMEOUT e CACHE_DURATION não seguem a regra: hoje a variável de ambiente vence o argumento do construtor. Passar timeout=30 no código não tem efeito se TIMEOUT existir no ambiente.

É dívida conhecida e está registrada. Consertar significa mudar os defaults de get_instance para None, o que altera uma assinatura pública — por isso está segurado para uma versão maior.

As variáveis

Conexão

Variável Alternativas Default
API_{INSTANCE}_URL API_PARAMS_URL, API_URL ''
TIMEOUT — 5
VERIFY_SSL {INSTANCE}_VERIFY_SSL False

A URL é resolvida nesta ordem: argumento api_url, depois API_{INSTANCE}_URL, depois API_PARAMS_URL, depois API_URL. Não há prefixo de instância nas duas últimas.

Credenciais

Variável Default
{INSTANCE}_PARAMS_USERNAME ou PARAMS_USERNAME (nenhum)
{INSTANCE}_PARAMS_PASSWORD ou PARAMS_PASSWORD (nenhum)

O tutorial antigo erra o nome

A documentação antiga fala em PARAM_MANAGER_USERNAME e PARAM_MANAGER_PASSWORD. Os nomes corretos são PARAMS_USERNAME e PARAMS_PASSWORD.

Cache e resiliência

Variável Alternativa Default
CACHE_DURATION {INSTANCE}_CACHE_DURATION 300 no construtor, 3600 em get_instance
API_ERROR_COOLDOWN {INSTANCE}_API_ERROR_COOLDOWN Cai para cache_duration

O default de cache depende de como você constrói

ParamManager(...) usa 300 s. ParamManager.get_instance(...) usa 3600 s. As duas formas são públicas e os dois valores estão no código. Se a validade do cache importa para você, passe o valor explicitamente.

Armazenamento local

Variável Default
LOCAL_DB_PATH Diretório do .env, ou o diretório corrente

O arquivo final fica em:

<base>/param_manager/<instance_name>/params_<instance_name>.json

A ordem de resolução da base é: argumento local_db_path, depois o diretório do PyInstaller quando congelado, depois LOCAL_DB_PATH, depois o diretório do .env, e por último o diretório de trabalho.

O caminho mudou na 0.4.0

A documentação antiga fala em param_manager/params_db.json, sem o nível da instância. Desde a 0.4.0 é um diretório por instância.

Criptografia

Variável Alternativa
CHAVE_CUSTODIA_APP APP_CUSTODY_KEY

Tem que casar com o APP_CUSTODY_KEY do servidor. Se não casar, a decifragem falha — e ela falha em silêncio: o cliente registra um erro no log e devolve None. O formato está descrito em Envelope criptográfico, no site do produto.

Cache legado

Variável Efeito
PARAM_MANAGER_PURGE_PLAINTEXT_CACHE Purga, na inicialização, cache local antigo gravado em claro

É opt-in. Ligue uma vez ao migrar de uma versão que gravava valor sensível sem cifrar.

verify_ssl tem escopo parcial

Este é o ponto mais fácil de diagnosticar errado da biblioteca inteira.

A flag governa apenas os dois GETs de leitura. Autenticação e escrita verificam a cadeia TLS sempre, e isso é deliberado: o POST /auth/token carrega usuário e senha, e rebaixar o TLS dele seria pior do que a assimetria.

O sintoma em ambiente com certificado interno

A leitura funciona e a autenticação falha por SSL. Parece configuração pela metade; é o comportamento projetado. A saída correta é instalar a cadeia interna no sistema, não procurar uma flag que desligue a verificação do login.

O default de verify_ssl é False, porque os ambientes que consomem a biblioteca usam certificado interno. Quem tem cadeia confiável pode — e deve — passar verify_ssl=True.

Os valores aceitos na variável de ambiente são 1, true, yes e on, sem diferenciar maiúsculas. Qualquer outra coisa é falso.

Exemplo de .env

API_PARAMS_URL=https://parametros.exemplo.com
PARAMS_USERNAME=servico-relatorios
PARAMS_PASSWORD=...
CACHE_DURATION=600
API_ERROR_COOLDOWN=60
VERIFY_SSL=true
CHAVE_CUSTODIA_APP=...

# Uma segunda instância, com sobrescritas próprias
API_HOMOLOG_URL=https://parametros-homolog.exemplo.com
HOMOLOG_CACHE_DURATION=30