Écrire des scripts

Un script, c'est de la logique en Python qui s'exécute sur le serveur, à l'intérieur de l'app. C'est la bonne pièce pour tout ce qui n'est ni un écran ni une requête simple : synchroniser des données avec un autre système, recalculer des indicateurs tous les matins, générer un Excel et l'envoyer par e-mail, valider un fichier chargé par une API.

Le même script peut être déclenché de trois manières — et le code ne change pas :

Déclenchement	Comment ça se passe
Manuel	Bouton Exécuter maintenant dans l'éditeur, avec des arguments facultatifs.
Cron	Une planification (chapitre Planifications) — à heures fixes, à intervalles réguliers, ou dans une fenêtre de surveillance.
API	Comme étape d'une API de l'app — le script reçoit les arguments de la requête et le résultat de l'étape précédente.

Tout au long de cette page, nous utilisons le script atualizar_indicadores de l'app Gestion des Clients, qui recalcule les indicateurs commerciaux du CRM tous les matins.

#Où vivent les scripts

Dans l'app, les scripts ont leur section dans l'arborescence latérale — le groupe Scripts. Chaque script est un nœud de l'arborescence : cliquer sur le nom ouvre l'éditeur dans un onglet de l'espace de travail, et la flèche à gauche déploie le nœud pour montrer ses Fichiers, ses Dépendances et ses Planifications (pages suivantes de ce chapitre).

Il y a aussi une vue en liste — la page Scripts — avec une ligne par script :

Colonne	Ce qu'elle montre
Nom	Nom et description du script.
Runtime	Le langage d'exécution (Python).
État	Actif ou Brouillon — seuls les actifs s'exécutent par planification.
Planifications	Combien de planifications existent, combien sont actives, et Prochaine : avec la date de la prochaine exécution prévue.
Dernière exécution	L'état (Succès, Erreur, …) et l'heure de l'exécution la plus récente.

#Créer un script

1. Dans l'arborescence latérale, passez la souris sur la ligne du groupe Scripts et cliquez sur le bouton + (Nouveau script).

2. Remplissez la fenêtre Nouveau script :

   Champ	Notes
   Nom	Obligatoire. Ex. : synchroniser-clients. C'est par ce nom que le script est référencé dans les planifications et dans les APIs.
   Runtime	Fixe : Python. L'exécution sur le serveur est uniquement en Python.
   Description	Facultatif — « Que fait ce script ? » apparaît dans la liste et dans l'arborescence.
   Temps limite	30 secondes, 1 minute, 2 minutes, 5 minutes ou 10 minutes. Une fois dépassé, le processus est arrêté et l'exécution est marquée comme timeout.

3. Cliquez sur Créer le script. Le script naît avec le code initial (le contrat sous les yeux, en commentaires) et l'éditeur s'ouvre aussitôt dans un onglet.

#Le contrat : main(input)

Tout script a un fichier d'entrée, main.py, avec une fonction main. La plateforme l'appelle à chaque exécution et la valeur renvoyée est le résultat du script :

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

Le paramètre input apporte toujours trois clés :

Clé	Contenu
input["args"]	Dictionnaire contenant les arguments de l'exécution — ceux que vous avez saisis dans la fenêtre Exécuter maintenant, ceux définis dans la planification, ou ceux que l'API a transmis. Les valeurs arrivent sous forme de texte.
input["prev"]	Le résultat de l'étape précédente, quand le script s'exécute au sein d'une API. Dans les exécutions manuelles et planifiées, c'est None.
input["context"]	Métadonnées de l'exécution : nom et identifiant du script, le déclenchement ("manual", "cron", "api" ou "catchup"), le numéro de l'exécution, et qui l'a appelée.

Règles du résultat :

• Il doit être sérialisable en JSON : dictionnaires, listes, textes, nombres, booléens ou None. Les objets d'autres types font échouer l'exécution.
• La taille maximale du résultat est de 32 Mo.
• Une exception non rattrapée fait terminer l'exécution en Erreur, avec la trace complète dans les logs.

Tout ce que vous imprimerez — avec print ou avec le log(...) du SDK — apparaît dans les logs de l'exécution, ligne par ligne. Pour accéder aux données, aux appels HTTP, aux secrets, aux notifications et bien plus, servez-vous du SDK api_manager, décrit dans la page Le SDK des scripts.

#L'éditeur

L'éditeur occupe l'onglet du script sur toute la largeur. Dans la barre au-dessus du code, vous voyez le chemin du fichier actif (main.py au départ) avec un point d'état à côté — Enregistré ou Modifications non enregistrées. Il n'y a pas de bouton pour enregistrer le code : les modifications s'enregistrent toutes seules environ une seconde après que vous arrêtez d'écrire.

À droite de la barre se trouvent les boutons :

Bouton	Ce qu'il fait
Exécuter maintenant (▶)	Enregistre tout et ouvre la boîte de dialogue d'exécution manuelle.
Exécutions	Ouvre l'historique des exécutions du script.
Prompt pour LLM	Ouvre un texte prêt à copier avec tout le contrat du SDK, pour demander le script à un assistant IA — voir Le SDK des scripts.
Agrandir l'éditeur	L'éditeur occupe alors tout l'écran ; Échap ou Réduire l'éditeur ramènent à la normale.

Pendant que vous écrivez du Python, l'éditeur complète tout seul : il suggère les modules et fonctions du SDK (db, http, log, …), vos propres fichiers et les packages pip installés dans l'environnement du script, il montre la signature des paramètres pendant que vous remplissez un appel, et de la documentation au survol d'un nom.

#Exécuter à la main

1. Cliquez sur Exécuter maintenant (▶). Ce qui reste à enregistrer est enregistré d'abord.
2. Dans la boîte de dialogue, définissez les arguments de cette exécution (facultatif) : cliquez sur Ajouter un argument et remplissez Nom (ex. : clientId) et Valeur. Les valeurs arrivent au script sous forme de texte, dans input["args"].
3. Cliquez sur Exécuter.

Le panneau Résultat de l'exécution, sous l'éditeur, montre aussitôt :

• l'état — Succès ou Erreur — et la durée en millisecondes ;
• la valeur renvoyée par main, formatée en JSON ;
• les Logs, avec chaque ligne écrite par log(...) ou print.

Si l'exécution échoue, le message d'erreur apparaît à la place du résultat, et la trace complète reste dans les logs.

#L'historique des exécutions

Cliquez sur Exécutions dans la barre de l'éditeur. La fenêtre liste toutes les exécutions du script, avec des filtres par état, source, durée et date :

Colonne	Contenu
Début	Date et heure auxquelles l'exécution a commencé.
Source	Manuel, Cron, API ou Rattrapage (exécution récupérée d'une planification restée en plan).
État	Voir le tableau ci-dessous.
Durée	En millisecondes.

Les états possibles :

État	Signifie
Succès	main a renvoyé un résultat sans erreur.
Erreur	Une exception non rattrapée, ou un résultat non sérialisable.
En cours	L'exécution n'est pas encore terminée.
Timeout	Elle a dépassé le Temps limite du script et a été arrêtée.
Interrompu	Le processus a été arrêté avant la fin (ex. : arrêt du serveur).
Ignoré (chevauchement)	Une planification s'est déclenchée alors que l'exécution précédente était encore en cours — celle-ci n'a jamais démarré.

Cliquez sur Détails dans une ligne pour la déplier : vous y voyez les Arguments avec lesquels elle s'est exécutée, le Résultat renvoyé, l'Erreur (s'il y en a eu une) et les Logs complets.

#Actif ou brouillon

Dans l'en-tête du panneau du script, il y a un interrupteur Actif. Un script dont l'interrupteur est éteint reste en Brouillon :

• il ne s'exécute pas par planification — les heures prévues sont enregistrées comme Ignorée, avec la note « Le script est en brouillon » ;
• il peut toujours être exécuté à la main dans l'éditeur, pour que vous le testiez à volonté.

C'est la façon de développer tranquillement : écrivez, testez avec Exécuter maintenant, et n'allumez Actif que lorsque le script est prêt à tourner tout seul.

#Paramètres du script

Ouvrez les Paramètres du script (dans le menu d'actions du script dans l'arborescence, ou par l'en-tête du panneau) pour modifier :

Champ	Notes
Nom	Le nom par lequel les planifications et les APIs le référencent.
Version	Affichée là où ce script est utilisé comme dépendance d'un autre (app/script@version).
Description	Texte libre.
Temps limite	Les mêmes options qu'à la création, de 30 secondes à 10 minutes.

Le runtime n'apparaît pas à l'édition — il est fixé à la création.

#Questions fréquentes

Pourquoi l'exécution apparaît-elle comme Timeout ? Le script a pris plus de temps que le Temps limite défini. Augmentez la limite dans les Paramètres du script (maximum : 10 minutes) ou divisez le travail — par exemple, traitez par lots plus petits à chaque exécution.

J'ai écrit dans l'éditeur et lancé aussitôt — est-ce l'ancienne version qui a tourné ? Non. Exécuter maintenant enregistre d'abord tout ce qui reste à enregistrer ; l'exécution utilise toujours ce qui est à l'écran.

Le résultat est bon mais les arguments arrivent « faux » ? Les arguments arrivent toujours sous forme de texte. Un argument limite = 10 arrive comme "10" — convertissez-le dans le code : int(input["args"].get("limite", 0)).

Puis-je conserver un état d'une exécution à l'autre ? Chaque exécution est un processus isolé — les variables ne survivent pas d'une exécution à la suivante. Pour persister quelque chose, écrivez un fichier dans le dossier du script (voir Dépendances et fichiers) ou stockez les données dans un datasource.