Ir para o conteúdo

Configurar Proxy Autenticado nas Ferramentas BotCity

Este guia mostra como fornecer as credenciais do proxy corporativo autenticado para as ferramentas do BotCity Studio SDK (Wizard, BotRunner, BotCLI, BotStudio, Diagnostic) e para as automações Python, garantindo que a instalação, a execução dos robôs e a comunicação com o Orquestrador passem pela autenticação da rede.

Versões mínimas

Em versões anteriores às listadas abaixo, as propriedades descritas neste guia são ignoradas.

  • Wizard 3.4.0
  • BotRunner 3.6.0
  • BotCLI 2.2.0
  • BotStudio 3.3.0
  • Diagnostic 1.4.0

As propriedades do proxy

A rede exige um usuário e uma senha para o proxy. Hoje essa credencial já é fornecida ao pip através do parâmetro --proxy. As aplicações Java do SDK precisam exatamente da mesma informação, mas fornecida como propriedades da JVM. Com as propriedades configuradas, as ferramentas enviam a credencial ao proxy logo na primeira requisição (o mesmo comportamento do pip) e a conexão é autorizada.

Existem oito propriedades. Preencha as quatro para https e repita os mesmos valores nas quatro para http:

-Dhttps.proxyHost=proxy.empresa.com
-Dhttps.proxyPort=porta
-Dhttps.proxyUser=usuario
-Dhttps.proxyPassword=senha
-Dhttp.proxyHost=proxy.empresa.com
-Dhttp.proxyPort=porta
-Dhttp.proxyUser=usuario
-Dhttp.proxyPassword=senha

Proxy sem usuário?

Se o seu proxy não exige autenticação, não defina proxyUser/proxyPassword com valores vazios. Nesse caso, remova completamente as quatro propriedades *User e *Password e mantenha apenas proxyHost e proxyPort. Um valor vazio ainda pode fazer o cliente enviar uma credencial em branco, o que alguns proxies rejeitam. O mesmo vale para as variáveis de ambiente do Python descritas mais abaixo: use http://host:porta, sem o trecho usuario:senha@.

Alternativas para configurar as propriedades do proxy

As mesmas oito propriedades podem chegar até as aplicações de duas formas. Apenas uma das opções já é suficiente, não é necessário fazer as duas.

Opção A: Configuração por aplicação, sem usar variável de ambiente

Nesse caso, é necessário criar um arquivo .ini ao lado de cada executável (.exe) e alterar uma linha nos scripts do Runner e do CLI.

1. Arquivo .ini ao lado dos executáveis

Crie o arquivo wizard-3.4.0.l4j.ini ao lado de wizard-3.4.0.exe com o seguinte conteúdo:

-Dhttps.proxyHost=proxy.empresa.com
-Dhttps.proxyPort=porta
-Dhttps.proxyUser=usuario
-Dhttps.proxyPassword=senha
-Dhttp.proxyHost=proxy.empresa.com
-Dhttp.proxyPort=porta
-Dhttp.proxyUser=usuario
-Dhttp.proxyPassword=senha

Após a instalação do SDK, essa mesma estratégia também pode ser usada para iniciar o BotStudio com as propriedades adequadas. Nesse caso, basta criar o arquivo BotStudio.l4j.ini ao lado de BotStudio.exe, com o mesmo conteúdo acima.

2. Propriedades nos scripts de inicialização do Runner e do CLI

Na pasta de instalação do SDK, edite os três scripts:

Arquivo Finalidade
BotRunnerBackgroundWrapper.bat Inicia o Runner em segundo plano
BotRunner-gui.bat Inicia o Runner com interface gráfica
BotCLI.bat Inicia a ferramenta de linha de comando

Em cada um, insira as propriedades entre java e -jar. Antes e depois, para o Runner:

Antes 

"%SCRIPTPATH%\win32\java\bin\java" -Dfile.encoding=UTF-8 -jar "%SCRIPTPATH%\bin\botrunner.jar"
Depois 
"%SCRIPTPATH%\win32\java\bin\java" -Dfile.encoding=UTF-8 "-Dhttps.proxyHost=proxy.empresa.com" "-Dhttps.proxyPort=porta" "-Dhttps.proxyUser=usuario" "-Dhttps.proxyPassword=senha" "-Dhttp.proxyHost=proxy.empresa.com" "-Dhttp.proxyPort=porta" "-Dhttp.proxyUser=usuario" "-Dhttp.proxyPassword=senha" -jar "%SCRIPTPATH%\bin\botrunner.jar"

Vantagens:

  • Não cria uma variável no escopo da máquina.
  • A credencial fica restrita apenas às aplicações do SDK.
  • Nenhuma outra aplicação Java na máquina é afetada.

Desvantagens:

  • Toda atualização ou nova instalação substitui os arquivos e exige refazer a configuração.
  • Existem vários arquivos para manter.

Opção B: Via variável de ambiente JAVA_TOOL_OPTIONS

Essa é a alternativa mais simples: uma única variável de ambiente no escopo da máquina, lida automaticamente por qualquer aplicação Java.

  • Nome da variável: JAVA_TOOL_OPTIONS
  • Valor da variável:
-Dhttps.proxyHost=proxy.empresa.com -Dhttps.proxyPort=porta -Dhttps.proxyUser=usuario -Dhttps.proxyPassword=senha -Dhttp.proxyHost=proxy.empresa.com -Dhttp.proxyPort=porta -Dhttp.proxyUser=usuario -Dhttp.proxyPassword=senha

Crie a variável em Propriedades do Sistema → Variáveis de Ambiente → Variáveis do sistema.

Tela de Variáveis de Ambiente do Windows mostrando a criação da variável de sistema JAVA_TOOL_OPTIONS com o valor das propriedades de proxy.

Reinicie após criar a variável

Depois de criar a variável, feche e reabra qualquer terminal e reinicie o Runner, o BotStudio e o próprio Wizard. Cada processo só lê o ambiente quando é iniciado.

Vantagens:

  • Configuração única, aplicada a todas as ferramentas.
  • Sobrevive a atualizações e reinstalações do SDK.

Desvantagens:

  • É uma variável no escopo da máquina: aplica-se a toda JVM no servidor.

Automações Python: substituir --proxy por variáveis de ambiente

Hoje, a instalação de pacotes é feita com pip install --proxy http://usuario:senha@proxy..., digitado manualmente. Isso precisa mudar por dois motivos:

  • É o Runner quem instala as dependências do robô. Toda vez que ele prepara um robô, executa o pip algumas vezes (atualizando pip, setuptools, wheel e depois o pacote ou requirements.txt), e não há onde digitar --proxy.
  • O código do robô também acessa a rede. Chamadas do SDK como maestro.finish_task() ou maestro.alert(), usadas em integrações com a plataforma, também podem falhar na autenticação do proxy se a credencial não estiver disponível. O --proxy do pip não alcança essas chamadas.

Variáveis de ambiente resolvem os dois casos de uma vez. Crie HTTP_PROXY e HTTPS_PROXY no escopo da Máquina, ou no escopo do usuário que executa o Runner. O valor é exatamente o mesmo que hoje é passado para a flag --proxy, no formato http://usuario:senha@host:porta.

Tela de Variáveis de Ambiente do Windows mostrando as variáveis de sistema HTTP_PROXY e HTTPS_PROXY, ambas com o valor http://user:password@host:port.

Reinicie o Runner após criar as variáveis

O Runner repassa aos robôs e ao pip o ambiente que recebeu quando foi iniciado.

Caracteres especiais na senha

Diferente das propriedades da JVM, onde a senha é escrita literalmente, aqui o usuário e a senha ficam dentro de uma URL. Qualquer caractere reservado precisa ser codificado, ou a URL é interpretada incorretamente e a autenticação falha:

Caractere Escrever como Caractere Escrever como
@ %40 # %23
: %3A & %26
/ %2F ? %3F
\ (domínio) %5C % %25

Exemplo: o usuário Lara com a senha p@ss:2026 vira http://Lara:p%40ss%3A2026@proxy.empresa.com:8080.

Ambientes virtuais

Como HTTP_PROXY/HTTPS_PROXY são lidas diretamente pelo pip e pela biblioteca requests, elas funcionam para qualquer venv, sem necessidade de configuração adicional por ambiente.

Solucionar problemas

Falha no login do Runner com código de status 400

Login failed with status code: 400

O log do Runner exibe as mensagens abaixo, e o Runner tenta o login novamente a cada 5 segundos sem conseguir se conectar ao Orquestrador:

Login failed with status code: 400
Failed to login with BotCity Orchestrator. We will retry in 5 seconds.
Obtaining an access token with BotCity Maestro.

Esse erro indica que as propriedades do proxy não chegaram ao Runner, porque não foram adicionadas aos scripts de inicialização do Runner (BotRunnerBackgroundWrapper.bat e BotRunner-gui.bat) ou foram adicionadas mal formatadas, por exemplo fora da posição entre java e -jar, sem aspas ou com algum valor digitado incorretamente.

Para corrigir: abra esses scripts e confirme que as oito propriedades estão presentes, entre java e -jar, no mesmo formato mostrado na Opção A. Ajuste o que estiver faltando ou mal formatado e reinicie o Runner. Se preferir não editar os scripts, use a Opção B, que aplica as propriedades a todas as ferramentas de uma vez.