Escrever scripts

Um script é lógica em Python que corre no servidor, dentro da app. É a peça certa para tudo o que não é um ecrã nem uma query simples: sincronizar dados com outro sistema, recalcular indicadores todas as manhãs, gerar um Excel e enviá-lo por email, validar um ficheiro carregado por uma API.

O mesmo script pode ser disparado de três maneiras — e o código não muda:

Disparo	Como acontece
Manual	Botão Executar agora no editor, com argumentos opcionais.
Cron	Um agendamento (capítulo Agendamentos) — a horas certas, em intervalos, ou numa janela de vigilância.
API	Como passo de uma API da app — o script recebe os argumentos do pedido e o resultado do passo anterior.

Ao longo desta página usamos o script atualizar_indicadores da app Gestão de Clientes, que recalcula os indicadores comerciais do CRM todas as manhãs.

#Onde vivem os scripts

Dentro da app, os scripts têm a sua secção na árvore lateral — o grupo Scripts. Cada script é um nó da árvore: clicar no nome abre o editor num separador do espaço de trabalho, e a seta à esquerda expande o nó para mostrar os Ficheiros, as Dependências e os Agendamentos dele (páginas seguintes deste capítulo).

Há também uma vista de lista — a página Scripts — com uma linha por script:

Coluna	O que mostra
Nome	Nome e descrição do script.
Runtime	A linguagem de execução (Python).
Estado	Activo ou Rascunho — só os activos correm por agendamento.
Agendamentos	Quantos agendamentos existem, quantos estão activos, e Próxima: com a data da próxima execução prevista.
Última execução	O estado (Sucesso, Erro, …) e a hora da execução mais recente.

#Criar um script

1. Na árvore lateral, passa o rato pela linha do grupo Scripts e clica no botão + (Novo script).

2. Preenche o modal Novo script:

   Campo	Notas
   Nome	Obrigatório. Ex.: sincronizar-clientes. É por este nome que o script é referenciado nos agendamentos e nas APIs.
   Runtime	Fixo: Python. A execução no servidor é só Python.
   Descrição	Opcional — "O que faz este script?" aparece na lista e na árvore.
   Tempo limite	30 segundos, 1 minuto, 2 minutos, 5 minutos ou 10 minutos. Ao exceder, o processo é terminado e a execução fica marcada como timeout.

3. Clica em Criar script. O script nasce com o código inicial (o contrato à vista, em comentários) e o editor abre de imediato num separador.

#O contrato: main(input)

Todo o script tem um ficheiro de entrada, main.py, com uma função main. A plataforma chama-a em cada execução e o valor devolvido é o resultado do script:

def main(input):
    return {"ok": True}

O parâmetro input traz sempre três chaves:

Chave	Conteúdo
input["args"]	Dicionário com os argumentos da execução — os que escreveste no modal Executar agora, os definidos no agendamento, ou os que a API passou. Os valores chegam como texto.
input["prev"]	O resultado do passo anterior, quando o script corre dentro de uma API. Nas execuções manuais e agendadas é None.
input["context"]	Metadados da execução: nome e identificador do script, o disparo ("manual", "cron", "api" ou "catchup"), o número da execução, e quem chamou.

Regras do resultado:

• Tem de ser serializável em JSON: dicionários, listas, textos, números, booleanos ou None. Objectos de outros tipos fazem a execução falhar.
• O tamanho máximo do resultado é 32 MB.
• Uma excepção não apanhada faz a execução terminar em Erro, com o traceback completo nos logs.

Tudo o que imprimires — com print ou com o log(...) do SDK — aparece nos logs da execução, linha a linha. Para aceder a dados, chamadas HTTP, segredos, notificações e mais, usa o SDK api_manager, descrito na página O SDK dos scripts.

#O editor

O editor ocupa o separador do script a toda a largura. Na barra por cima do código vês o caminho do ficheiro activo (main.py ao início) com um ponto de estado ao lado — Guardado ou Alterações por guardar. Não há botão de gravar código: as alterações gravam-se sozinhas cerca de um segundo depois de parares de escrever.

À direita da barra estão os botões:

Botão	O que faz
Executar agora (▶)	Grava tudo e abre o diálogo de execução manual.
Execuções	Abre o histórico de execuções do script.
Prompt para LLM	Abre um texto pronto a copiar com todo o contrato do SDK, para pedir o script a um assistente de IA — ver O SDK dos scripts.
Maximizar editor	O editor passa a ocupar o ecrã inteiro; Esc ou Minimizar editor voltam ao normal.

Enquanto escreves Python, o editor autocompleta: sugere os módulos e funções do SDK (db, http, log, …), os teus próprios ficheiros e os packages pip instalados no ambiente do script, mostra a assinatura dos parâmetros enquanto preenches uma chamada, e documentação ao pairar sobre um nome.

#Executar à mão

1. Clica em Executar agora (▶). O que estiver por gravar é gravado primeiro.
2. No diálogo, define os argumentos desta execução (opcional): clica em Adicionar argumento e preenche Nome (ex.: clienteId) e Valor. Os valores chegam ao script como texto, em input["args"].
3. Clica em Executar.

O painel Resultado da execução, por baixo do editor, mostra de imediato:

• o estado — Sucesso ou Erro — e a duração em milissegundos;
• o valor devolvido por main, formatado como JSON;
• os Logs, com cada linha escrita por log(...) ou print.

Se a execução falhar, a mensagem de erro aparece no lugar do resultado, e o traceback completo fica nos logs.

#O histórico de execuções

Clica em Execuções na barra do editor. O modal lista todas as execuções do script, com filtros por estado, origem, duração e data:

Coluna	Conteúdo
Início	Data e hora em que a execução começou.
Origem	Manual, Cron, API ou Recuperação (execução recuperada de um agendamento que ficou por correr).
Estado	Ver tabela abaixo.
Duração	Em milissegundos.

Os estados possíveis:

Estado	Significa
Sucesso	main devolveu um resultado sem erro.
Erro	Uma excepção não apanhada, ou um resultado não serializável.
A correr	A execução ainda não terminou.
Timeout	Excedeu o Tempo limite do script e foi terminada.
Abortado	O processo foi terminado antes do fim (ex.: paragem do servidor).
Saltado (sobreposição)	Um agendamento disparou enquanto a execução anterior ainda decorria — esta não chegou a correr.

Clica em Detalhes numa linha para a expandir: vês os Argumentos com que correu, o Resultado devolvido, o Erro (se houve) e os Logs completos.

#Activo ou rascunho

No cabeçalho do painel do script há um interruptor Activo. Um script com o interruptor desligado fica em Rascunho:

• não corre por agendamento — as horas previstas ficam registadas como Saltada, com a nota "O script está em rascunho";
• continua a poder ser executado à mão no editor, para o testares à vontade.

É a forma de desenvolver com calma: escreve, testa com Executar agora, e só liga o Activo quando o script estiver pronto a correr sozinho.

#Definições do script

Abre as Definições do script (no menu de acções do script na árvore, ou pelo cabeçalho do painel) para alterar:

Campo	Notas
Nome	O nome pelo qual agendamentos e APIs o referenciam.
Versão	Mostrada onde este script é usado como dependência de outro (app/script@versão).
Descrição	Texto livre.
Tempo limite	As mesmas opções da criação, de 30 segundos a 10 minutos.

O runtime não aparece para edição — fica definido na criação.

#Perguntas frequentes

Porque é que a execução aparece como Timeout? O script demorou mais do que o Tempo limite definido. Sobe o limite nas Definições do script (máximo: 10 minutos) ou divide o trabalho — por exemplo, processa em lotes mais pequenos por execução.

Escrevi no editor e corri logo — correu a versão antiga? Não. Executar agora grava primeiro tudo o que estiver por gravar; a execução usa sempre o que está no ecrã.

O resultado devolve bem mas os argumentos chegam "errados"? Os argumentos chegam sempre como texto. Um argumento limite = 10 chega como "10" — converte no código: int(input["args"].get("limite", 0)).

Posso guardar estado entre execuções? Cada execução é um processo isolado — variáveis não sobrevivem de uma para a outra. Para persistir alguma coisa, escreve um ficheiro na pasta do script (ver Dependências e ficheiros) ou guarda os dados num datasource.