Scrivere script

Uno script è logica in Python che viene eseguita sul server, dentro l'app. È il pezzo giusto per tutto ciò che non è una schermata né una query semplice: sincronizzare dati con un altro sistema, ricalcolare indicatori ogni mattina, generare un Excel e inviarlo per email, convalidare un file caricato da un'API.

Lo stesso script può essere attivato in tre modi — e il codice non cambia:

Attivazione	Come avviene
Manuale	Pulsante Esegui ora nell'editor, con argomenti opzionali.
Cron	Una pianificazione (capitolo Pianificazioni) — a ore precise, a intervalli, o in una finestra di sorveglianza.
API	Come passaggio di un'API dell'app — lo script riceve gli argomenti della richiesta e il risultato del passaggio precedente.

In questa pagina usiamo lo script atualizar_indicadores dell'app Gestione Clienti, che ricalcola gli indicatori commerciali del CRM ogni mattina.

#Dove vivono gli script

Dentro l'app, gli script hanno la loro sezione nell'albero laterale — il gruppo Script. Ogni script è un nodo dell'albero: cliccare sul nome apre l'editor in una scheda dello spazio di lavoro, e la freccia a sinistra espande il nodo per mostrare i File, le Dipendenze e le Pianificazioni dello script (pagine successive di questo capitolo).

C'è anche una vista a elenco — la pagina Script — con una riga per script:

Colonna	Cosa mostra
Nome	Nome e descrizione dello script.
Runtime	Il linguaggio di esecuzione (Python).
Stato	Attivo o Bozza — solo quelli attivi vengono eseguiti dalle pianificazioni.
Pianificazioni	Quante pianificazioni esistono, quante sono attive, e Prossima: con la data della prossima esecuzione prevista.
Ultima esecuzione	Lo stato (Riuscito, Errore, …) e l'ora dell'esecuzione più recente.

#Creare uno script

1. Nell'albero laterale, passa il mouse sulla riga del gruppo Script e clicca sul pulsante + (Nuovo script).

2. Compila la finestra Nuovo script:

   Campo	Note
   Nome	Obbligatorio. Es.: sincronizar-clientes. È con questo nome che lo script viene richiamato nelle pianificazioni e nelle API.
   Runtime	Fisso: Python. L'esecuzione sul server è solo Python.
   Descrizione	Opzionale — "Cosa fa questo script?" compare nell'elenco e nell'albero.
   Limite di tempo	30 secondi, 1 minuto, 2 minuti, 5 minuti o 10 minuti. Al superamento, il processo viene terminato e l'esecuzione viene contrassegnata come timeout.

3. Clicca su Crea script. Lo script nasce con il codice iniziale (il contratto bene in vista, nei commenti) e l'editor si apre subito in una scheda.

#Il contratto: main(input)

Ogni script ha un file di ingresso, main.py, con una funzione main. La piattaforma la chiama a ogni esecuzione e il valore restituito è il risultato dello script:

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

Il parametro input porta sempre tre chiavi:

Chiave	Contenuto
input["args"]	Dizionario con gli argomenti dell'esecuzione — quelli che hai scritto nella finestra Esegui ora, quelli definiti nella pianificazione, o quelli passati dall'API. I valori arrivano come testo.
input["prev"]	Il risultato del passaggio precedente, quando lo script viene eseguito dentro un'API. Nelle esecuzioni manuali e pianificate è None.
input["context"]	Metadati dell'esecuzione: nome e identificatore dello script, l'attivazione ("manual", "cron", "api" o "catchup"), il numero dell'esecuzione, e chi l'ha chiamata.

Regole del risultato:

• Deve essere serializzabile in JSON: dizionari, liste, testi, numeri, booleani o None. Oggetti di altri tipi fanno fallire l'esecuzione.
• La dimensione massima del risultato è 32 MB.
• Un'eccezione non gestita fa terminare l'esecuzione in Errore, con il traceback completo nei log.

Tutto quello che stampi — con print o con il log(...) dell'SDK — compare nei log dell'esecuzione, riga per riga. Per accedere ai dati, alle chiamate HTTP, ai segreti, alle notifiche e altro ancora, usa l'SDK api_manager, descritto nella pagina L'SDK degli script.

#L'editor

L'editor occupa la scheda dello script per tutta la larghezza. Nella barra sopra il codice vedi il percorso del file attivo (main.py all'inizio) con un punto di stato accanto — Salvato o Modifiche non salvate. Non c'è un pulsante per salvare il codice: le modifiche si salvano da sole circa un secondo dopo che smetti di scrivere.

A destra della barra ci sono i pulsanti:

Pulsante	Cosa fa
Esegui ora (▶)	Salva tutto e apre la finestra di esecuzione manuale.
Esecuzioni	Apre la cronologia delle esecuzioni dello script.
Prompt per LLM	Apre un testo pronto da copiare con tutto il contratto dell'SDK, per chiedere lo script a un assistente di IA — vedi L'SDK degli script.
Massimizza editor	L'editor passa a occupare tutto lo schermo; Esc o Minimizza editor tornano alla normalità.

Mentre scrivi Python, l'editor completa automaticamente: suggerisce i moduli e le funzioni dell'SDK (db, http, log, …), i tuoi stessi file e i package pip installati nell'ambiente dello script, mostra la firma dei parametri mentre compili una chiamata, e la documentazione al passaggio del mouse su un nome.

#Eseguire a mano

1. Clicca su Esegui ora (▶). Tutto quello che è da salvare viene salvato prima.
2. Nella finestra, definisci gli argomenti di questa esecuzione (opzionale): clicca su Aggiungi argomento e compila Nome (es.: clienteId) e Valore. I valori arrivano allo script come testo, in input["args"].
3. Clicca su Esegui.

Il pannello Esito dell'esecuzione, sotto l'editor, mostra subito:

• lo stato — Riuscito o Errore — e la durata in millisecondi;
• il valore restituito da main, formattato come JSON;
• i Log, con ogni riga scritta da log(...) o print.

Se l'esecuzione fallisce, il messaggio di errore compare al posto del risultato, e il traceback completo resta nei log.

#La cronologia delle esecuzioni

Clicca su Esecuzioni nella barra dell'editor. La finestra elenca tutte le esecuzioni dello script, con filtri per stato, origine, durata e data:

Colonna	Contenuto
Inizio	Data e ora in cui l'esecuzione è cominciata.
Origine	Manuale, Cron, API o Recupero (esecuzione recuperata da una pianificazione rimasta da eseguire).
Stato	Vedi la tabella qui sotto.
Durata	In millisecondi.

Gli stati possibili:

Stato	Significa
Riuscito	main ha restituito un risultato senza errore.
Errore	Un'eccezione non gestita, o un risultato non serializzabile.
In esecuzione	L'esecuzione non è ancora terminata.
Timeout	Ha superato il Limite di tempo dello script ed è stata terminata.
Interrotto	Il processo è stato terminato prima della fine (es.: arresto del server).
Saltato (sovrapposizione)	Una pianificazione è scattata mentre l'esecuzione precedente era ancora in corso — questa non è mai partita.

Clicca su Dettagli in una riga per espanderla: vedi gli Argomenti con cui è stata eseguita, il Risultato restituito, l'Errore (se c'è stato) e i Log completi.

#Attivo o bozza

Nell'intestazione del pannello dello script c'è un interruttore Attivo. Uno script con l'interruttore spento resta in Bozza:

• non viene eseguito dalle pianificazioni — le ore previste vengono registrate come Saltata, con la nota "Lo script è in bozza";
• può comunque essere eseguito a mano nell'editor, per provarlo con calma.

È il modo di sviluppare senza fretta: scrivi, prova con Esegui ora, e accendi l'Attivo solo quando lo script è pronto a funzionare da solo.

#Impostazioni dello script

Apri le Impostazioni dello script (dal menu delle azioni dello script nell'albero, o dall'intestazione del pannello) per modificare:

Campo	Note
Nome	Il nome con cui pianificazioni e API lo richiamano.
Versione	Mostrata dove questo script è usato come dipendenza di un altro (app/script@versão).
Descrizione	Testo libero.
Limite di tempo	Le stesse opzioni della creazione, da 30 secondi a 10 minuti.

Il runtime non compare fra i campi modificabili — viene definito alla creazione.

#Domande frequenti

Perché l'esecuzione compare come Timeout? Lo script ha impiegato più del Limite di tempo definito. Alza il limite nelle Impostazioni dello script (massimo: 10 minuti) oppure dividi il lavoro — per esempio, elabora in lotti più piccoli per esecuzione.

Ho scritto nell'editor e ho eseguito subito — è stata eseguita la versione vecchia? No. Esegui ora salva prima tutto quello che è da salvare; l'esecuzione usa sempre quello che è sullo schermo.

Il risultato torna bene ma gli argomenti arrivano "sbagliati"? Gli argomenti arrivano sempre come testo. Un argomento limite = 10 arriva come "10" — convertilo nel codice: int(input["args"].get("limite", 0)).

Posso conservare uno stato fra un'esecuzione e l'altra? Ogni esecuzione è un processo isolato — le variabili non sopravvivono da una all'altra. Per persistere qualcosa, scrivi un file nella cartella dello script (vedi Dipendenze e file) oppure salva i dati in un datasource.