Skripte schreiben

Ein Skript ist Logik in Python, die auf dem Server läuft, innerhalb der App. Es ist das richtige Bauteil für alles, was weder ein Bildschirm noch eine einfache Abfrage ist: Daten mit einem anderen System synchronisieren, jeden Morgen Kennzahlen neu berechnen, ein Excel erzeugen und per E-Mail versenden, eine über eine API hochgeladene Datei prüfen.

Dasselbe Skript kann auf drei Arten ausgelöst werden — und der Code ändert sich dabei nicht:

Auslöser	Wie es passiert
Manuell	Schaltfläche Jetzt ausführen im Editor, mit optionalen Argumenten.
Cron	Ein Zeitplan (Kapitel Zeitpläne) — zu festen Uhrzeiten, in Intervallen oder in einem Überwachungsfenster.
API	Als Schritt einer API der App — das Skript erhält die Argumente der Anfrage und das Ergebnis des vorherigen Schritts.

Auf dieser Seite verwenden wir durchgehend das Skript atualizar_indicadores der App Kundenverwaltung, das jeden Morgen die Vertriebskennzahlen des CRM neu berechnet.

#Wo die Skripte wohnen

Innerhalb der App haben die Skripte ihren eigenen Bereich im seitlichen Baum — die Gruppe Skripte. Jedes Skript ist ein Knoten des Baums: Ein Klick auf den Namen öffnet den Editor in einem Tab des Arbeitsbereichs, und der Pfeil links klappt den Knoten auf und zeigt dessen Dateien, Abhängigkeiten und Zeitpläne (die folgenden Seiten dieses Kapitels).

Es gibt auch eine Listenansicht — die Seite Skripte — mit einer Zeile pro Skript:

Spalte	Was sie zeigt
Name	Name und Beschreibung des Skripts.
Runtime	Die Ausführungssprache (Python).
Status	Aktiv oder Entwurf — nur die aktiven laufen nach Zeitplan.
Zeitpläne	Wie viele Zeitpläne es gibt, wie viele davon aktiv sind, und Nächste: mit dem Datum der nächsten geplanten Ausführung.
Letzte Ausführung	Der Status (Erfolg, Fehler, …) und die Uhrzeit der jüngsten Ausführung.

#Ein Skript erstellen

1. Fahren Sie im seitlichen Baum mit der Maus über die Zeile der Gruppe Skripte und klicken Sie auf die Schaltfläche + (Neues Skript).

2. Füllen Sie das Fenster Neues Skript aus:

   Feld	Hinweise
   Name	Pflichtfeld. Z. B.: kunden-synchronisieren. Unter diesem Namen wird das Skript in Zeitplänen und APIs referenziert.
   Runtime	Fest: Python. Die Ausführung auf dem Server ist nur mit Python möglich.
   Beschreibung	Optional — „Was macht dieses Skript?“ erscheint in der Liste und im Baum.
   Zeitlimit	30 Sekunden, 1 Minute, 2 Minuten, 5 Minuten oder 10 Minuten. Bei Überschreitung wird der Prozess beendet und die Ausführung als Timeout markiert.

3. Klicken Sie auf Skript erstellen. Das Skript entsteht mit dem Anfangscode (der Vertrag im Blick, als Kommentare) und der Editor öffnet sich sofort in einem Tab.

#Der Vertrag: main(input)

Jedes Skript hat eine Einstiegsdatei, main.py, mit einer Funktion main. Die Plattform ruft sie bei jeder Ausführung auf, und der zurückgegebene Wert ist das Ergebnis des Skripts:

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

Der Parameter input bringt immer drei Schlüssel mit:

Schlüssel	Inhalt
input["args"]	Dictionary mit den Argumenten der Ausführung — jenen, die Sie im Fenster Jetzt ausführen eingetragen haben, jenen aus dem Zeitplan oder jenen, die die API übergeben hat. Die Werte kommen als Text an.
input["prev"]	Das Ergebnis des vorherigen Schritts, wenn das Skript innerhalb einer API läuft. Bei manuellen und geplanten Ausführungen ist es None.
input["context"]	Metadaten der Ausführung: Name und Kennung des Skripts, der Auslöser ("manual", "cron", "api" oder "catchup"), die Nummer der Ausführung und wer sie aufgerufen hat.

Regeln für das Ergebnis:

• Es muss JSON-serialisierbar sein: Dictionaries, Listen, Texte, Zahlen, Booleans oder None. Objekte anderer Typen lassen die Ausführung fehlschlagen.
• Die maximale Größe des Ergebnisses beträgt 32 MB.
• Eine nicht abgefangene Ausnahme lässt die Ausführung mit Fehler enden, mit dem vollständigen Traceback in den Logs.

Alles, was Sie ausgeben — mit print oder mit dem log(...) des SDK — erscheint Zeile für Zeile in den Logs der Ausführung. Für den Zugriff auf Daten, HTTP-Aufrufe, Geheimnisse, Benachrichtigungen und mehr verwenden Sie das SDK api_manager, beschrieben auf der Seite Das SDK der Skripte.

#Der Editor

Der Editor füllt den Tab des Skripts in voller Breite. In der Leiste über dem Code sehen Sie den Pfad der aktiven Datei (anfangs main.py) mit einem Statuspunkt daneben — Gespeichert oder Ungespeicherte Änderungen. Es gibt keine Schaltfläche zum Speichern des Codes: Die Änderungen speichern sich von selbst, etwa eine Sekunde nachdem Sie aufhören zu tippen.

Rechts in der Leiste stehen die Schaltflächen:

Schaltfläche	Was sie tut
Jetzt ausführen (▶)	Speichert alles und öffnet den Dialog für die manuelle Ausführung.
Ausführungen	Öffnet die Ausführungshistorie des Skripts.
Prompt für LLM	Öffnet einen fertigen Text zum Kopieren mit dem vollständigen Vertrag des SDK, um das Skript von einem KI-Assistenten schreiben zu lassen — siehe Das SDK der Skripte.
Editor maximieren	Der Editor nimmt den ganzen Bildschirm ein; Esc oder Editor minimieren kehren zur Normalansicht zurück.

Während Sie Python schreiben, vervollständigt der Editor automatisch: Er schlägt die Module und Funktionen des SDK vor (db, http, log, …), Ihre eigenen Dateien und die pip-Pakete, die in der Umgebung des Skripts installiert sind, zeigt die Signatur der Parameter, während Sie einen Aufruf ausfüllen, und Dokumentation beim Überfahren eines Namens.

#Von Hand ausführen

1. Klicken Sie auf Jetzt ausführen (▶). Was noch nicht gespeichert ist, wird zuerst gespeichert.
2. Legen Sie im Dialog die Argumente dieser Ausführung fest (optional): Klicken Sie auf Argument hinzufügen und füllen Sie Name (z. B.: clienteId) und Wert aus. Die Werte kommen als Text beim Skript an, in input["args"].
3. Klicken Sie auf Ausführen.

Das Panel Ergebnis der Ausführung unterhalb des Editors zeigt sofort:

• den Status — Erfolg oder Fehler — und die Dauer in Millisekunden;
• den von main zurückgegebenen Wert, als JSON formatiert;
• die Logs, mit jeder von log(...) oder print geschriebenen Zeile.

Schlägt die Ausführung fehl, erscheint die Fehlermeldung anstelle des Ergebnisses, und der vollständige Traceback bleibt in den Logs.

#Die Ausführungshistorie

Klicken Sie in der Leiste des Editors auf Ausführungen. Das Fenster listet alle Ausführungen des Skripts auf, mit Filtern nach Status, Auslöser, Dauer und Datum:

Spalte	Inhalt
Start	Datum und Uhrzeit, zu der die Ausführung begonnen hat.
Auslöser	Manuell, Cron, API oder Nachholung (nachgeholte Ausführung eines Zeitplans, der nicht gelaufen ist).
Status	Siehe Tabelle unten.
Dauer	In Millisekunden.

Die möglichen Status:

Status	Bedeutet
Erfolg	main hat ein Ergebnis ohne Fehler zurückgegeben.
Fehler	Eine nicht abgefangene Ausnahme oder ein nicht serialisierbares Ergebnis.
Läuft	Die Ausführung ist noch nicht beendet.
Timeout	Sie hat das Zeitlimit des Skripts überschritten und wurde beendet.
Abgebrochen	Der Prozess wurde vor dem Ende beendet (z. B. Herunterfahren des Servers).
Übersprungen (Überschneidung)	Ein Zeitplan hat ausgelöst, während die vorherige Ausführung noch lief — diese hier ist gar nicht erst gelaufen.

Klicken Sie in einer Zeile auf Details, um sie aufzuklappen: Sie sehen die Argumente, mit denen sie lief, das zurückgegebene Ergebnis, den Fehler (falls es einen gab) und die vollständigen Logs.

#Aktiv oder Entwurf

In der Kopfzeile des Skript-Panels gibt es einen Schalter Aktiv. Ein Skript mit ausgeschaltetem Schalter bleibt im Entwurf:

• Es läuft nicht nach Zeitplan — die vorgesehenen Uhrzeiten werden als Übersprungen vermerkt, mit dem Hinweis „Das Skript ist im Entwurf“;
• es kann weiterhin von Hand im Editor ausgeführt werden, damit Sie es in Ruhe testen können.

So entwickelt man mit Gelassenheit: schreiben, mit Jetzt ausführen testen und Aktiv erst einschalten, wenn das Skript bereit ist, allein zu laufen.

#Einstellungen des Skripts

Öffnen Sie die Einstellungen des Skripts (im Aktionsmenü des Skripts im Baum oder über die Kopfzeile des Panels), um Folgendes zu ändern:

Feld	Hinweise
Name	Der Name, unter dem Zeitpläne und APIs es referenzieren.
Version	Wird dort angezeigt, wo dieses Skript als Abhängigkeit eines anderen verwendet wird (app/skript@version).
Beschreibung	Freier Text.
Zeitlimit	Dieselben Optionen wie bei der Erstellung, von 30 Sekunden bis 10 Minuten.

Die Runtime erscheint nicht zur Bearbeitung — sie wird bei der Erstellung festgelegt.

#Häufige Fragen

Warum erscheint die Ausführung als Timeout? Das Skript hat länger gebraucht als das festgelegte Zeitlimit. Erhöhen Sie das Limit in den Einstellungen des Skripts (Maximum: 10 Minuten) oder teilen Sie die Arbeit auf — verarbeiten Sie zum Beispiel kleinere Stapel pro Ausführung.

Ich habe im Editor geschrieben und sofort ausgeführt — lief die alte Version? Nein. Jetzt ausführen speichert zuerst alles, was noch offen ist; die Ausführung verwendet immer das, was auf dem Bildschirm steht.

Das Ergebnis stimmt, aber die Argumente kommen „falsch“ an? Die Argumente kommen immer als Text an. Ein Argument limite = 10 kommt als "10" an — wandeln Sie es im Code um: int(input["args"].get("limite", 0)).

Kann ich Zustand zwischen Ausführungen speichern? Jede Ausführung ist ein isolierter Prozess — Variablen überleben nicht von einer zur nächsten. Um etwas dauerhaft zu speichern, schreiben Sie eine Datei in den Ordner des Skripts (siehe Abhängigkeiten und Dateien) oder legen Sie die Daten in einer Datenquelle ab.