Script

Script ist ein deklarativer Backend-Endpunkt, den ein Frontend über HTTP aufruft. Statt Servercode zu schreiben, deklarieren Sie in JSON, "was zu tun ist", und die WEEGLOO-Engine führt es für Sie aus. Ziel ist es, mit einem einzigen Script die typische Backend-Verdrahtung zu ersetzen, die ein Frontend stützt (ein BFF, Backend-for-Frontend): Authentifizierung, Bedingungsprüfungen (Guards), verkettete CRUD-Operationen, Aufrufe externer APIs und die Aufbereitung von Werten.

Dieser Dokumentsatz ist die Referenz für die Script-Syntax. Die Details der einzelnen Syntaxbestandteile werden unten in Dokumente dieser Gruppe getrennt behandelt.

Das Erstellen und Verwalten eines Script (erstellen, abfragen, ändern, löschen) erfolgt auf der CMA (https://cma.weegloo.com/v1). Für die Ausführung ist der Ausführungspfad des dedizierten Script-Hosts (https://script.weegloo.com/v1) zuständig. Dieser eine Ausführungspfad akzeptiert beide: ein Weegloo-User-Token und das Token eines Mitglieds, das sich für das Produkt registriert hat (ein ServiceUser). Auf der ACMA gibt es keine Script-API, und auf den schreibgeschützten Delivery-APIs (CDA, ACDA) ebenfalls nicht.

Mentales Modell

• Ein Script ist ein HTTP-Endpunkt. Über die Aufrufmethode (method) wird abgeglichen, welches Script ausgeführt wird.
• Der Rumpf ist ein statements-Array. Es wird sequenziell von oben nach unten ausgeführt. Das ist wie der Rumpf einer Funktion in der gewöhnlichen Programmierung.
• Es ist Deklaration, nicht Code. Sie betten keinen beliebigen Code (FaaS) ein, sondern kombinieren vordefinierte Statement-Typen. Es ist weniger für das manuelle Verfassen durch einen Menschen ausgelegt als für die Generierung durch einen AI-Agenten über MCP.
• Werte fließen durch JSON-Pointer-Vorlagen. Sie referenzieren das Ergebnis eines vorherigen Schritts, den eingehenden payload oder eine Variable mit { /pointer } und geben es an den nächsten Schritt weiter. Wenn Sie eine Bedingung oder eine Berechnung benötigen, verwenden Sie JsonLogic-Operatoren. Die ausführlichen Regeln werden in Wertausdrücke behandelt.

Struktur der obersten Ebene (ScriptDefinition)

Ein einzelnes Script wird mit der folgenden ScriptDefinition-Struktur definiert.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. Beim Aufruf abgeglichene HTTP-Methode (erforderlich)
  "payloadSchema": { /* ... */ }, // (optional) JSON Schema. Falls vorhanden, wird der Request-payload vor der Ausführung validiert
  "statements": [ /* Statement[]. Von oben nach unten ausgeführt (erforderlich, mindestens 1) */ ]
}

Der payload akzeptiert nur JSON-Objekte. Auf den Aufruf-Body wird über die Kontextwurzel /payload zugegriffen ({ /payload/... }), und wenn Sie den Originalstring vor dem Parsen benötigen, über /rawPayload (etwa bei einer Signaturprüfung, die über den gesendeten Bytes rechnet). Die HTTP-Header der Anfrage werden über die Wurzel /headers referenziert ({ /headers/... }, Schlüssel in Kleinbuchstaben). Der Zeitpunkt, zu dem die Ausführung begonnen hat, liegt in der Wurzel /now. Die vollständige Menge der Kontextwurzeln wird in Wertausdrücke behandelt.

Anfrage und Antwort

Ein Script gibt letztlich den Wert seines Return-Statements an den Aufrufer zurück. Die Form der Antwort sieht wie folgt aus.

{
  "requestId": "…",     // Ausführungskennung
  "durationMs": 1234,   // Ausführungsdauer (ms)
  "statusCode": 200,    // statusCode des erreichten Return (Standard 200)
  "return": <value>     // Nur wenn Return.isError false ist. Ist der Wert null, dann ""
  // "error": <value>   // Wenn Return.isError true ist oder wenn die Ausführung fehlgeschlagen ist (dann fehlt "return"). Ist der Wert null, dann ""
}

• requestId ist die Kennung dieser Ausführung. Derselbe Wert landet im sys.requestId des ScriptLog, das diese Ausführung hinterlässt, und ist damit der Schlüssel, um diese Ausführung im Log zu finden.
• return und error erscheinen nie zusammen. Das isError des Return-Statements entscheidet, welches von beiden es ist.
• Wenn das Script bis zum Ende läuft, ohne ein Return-Statement zu erreichen, fehlen return und error beide, und statusCode ist der Standardwert (200).
• Schlägt die Ausführung fehl, wird error auch ohne Return gefüllt. Schlägt sie aus einem Grund auf der Aufrufseite fehl, etwa wegen eines fehlerhaften payload, und fängt Try das nicht ab, steht in error die Fehlerursache, und statusCode wird der Code, der diesem Fehlschlag entspricht (ein fehlerhafter payload ergibt 4xx, ein fehlgeschlagener externer Aufruf oder Mailversand 502). Das ist die Fehlerantwort, der man in der Praxis am häufigsten begegnet. Eine Ausführung, die das Zeitbudget überschreitet, antwortet nicht mit diesem Umschlag, sondern mit 408.
• Ist ein Wert null, wird das betreffende Feld als leerer String "" ausgegeben.

Mit value, isError und statusCode des Return steuern Sie den Antwort-Body und den Statuscode. Details werden in Return im Statement-Katalog behandelt.

Die Zeit für eine einzelne Ausführung

Ein Script wird inline auf dem Pfad ausgeführt, der die Aufrufanfrage verarbeitet. Es gibt keinen Ablauf, der die Arbeit in den Hintergrund verlagert oder zuerst eine Annahmebestätigung zurückgibt, und der Antwort-Body des Aufrufs ist unmittelbar das Ausführungsergebnis. Es gibt auch keinen Polling-Pfad, um das Ergebnis später abzuholen.

Die Zeit für eine einzelne Ausführung wird durch eine einzige Formel bestimmt: min(30 Sekunden + Summe der von den Statements deklarierten Zeiten, 180 Sekunden).

• Das Grundbudget beträgt 30 Sekunden. Dazu wird die von jedem Statement deklarierte Zeit addiert.
• Ein Statement ohne Deklaration zählt 0 Sekunden. Die Zeit, die dieses Statement tatsächlich verbraucht, geht vom Grundbudget von 30 Sekunden ab.
• Übersteigt die Summe 180 Sekunden, wird nicht das Speichern abgelehnt, sondern das Budget auf 180 Sekunden gekappt.

Hier die Kernpunkte der Deklarationsregeln je Statement.

• Iteration bedeutet Multiplikation. Loop und ResourceForEach multiplizieren die vom body (onEach) deklarierte Zeit mit der Obergrenze der Iterationen.
• Bei einer Iteration ohne externen Aufruf ist die deklarierte Zeit des body 0, daher ist das Grundbudget von 30 Sekunden die tatsächliche Grenze.

Die ausführlichen Regeln je Statement und die Plan-Grenzwerte werden in Ausführungssemantik, Einschränkungen und Sicherheit behandelt.

Minimales Beispiel

Erstellt aus Titel und Text im Request-payload einen Beitrags-Content, veröffentlicht ihn sofort und gibt anschließend die erzeugte sys.id zurück.

{
  "method": "Post",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate erstellt den Content und bindet das Ergebnis an den Namen post.
• Return gibt { "id": <neue Content-id> } mit 201 zurück.
• Warum die fields-Werte in einem Content Locale-Maps sind ({ "en-US": ... }), wird in Locale-Maps in den Wertausdrücken behandelt.

Weitere, vielfältigere Szenarien finden Sie im Cookbook.

Dokumente dieser Gruppe

• Wertausdrücke: Behandelt { /pointer }-Referenzen, Literale, JsonLogic-Operationen und -Bedingungen, Kontextwurzeln und Locale-Maps. Das ist der Kern der Syntax.
• Statement-Katalog: Behandelt die Felder und Ergebnisse der 25 Statement-Typen (Ressourcen-CRUD und -Lesen, Http, EmailSend, SetVar, Cache, ParseJson, Signature, Hash, Regex, If, Loop, Parallel, Try, Return).
• Ausführungssemantik, Einschränkungen und Sicherheit: Behandelt Ausführungsreihenfolge, Guards, Kompensation, optimistisches Sperren, Fehler, statische Einschränkungen und Plan-Grenzwerte sowie das Sicherheitsmodell.
• Cookbook: Behandelt vollständige Beispiele wie upsert, einen Credit-Guard, einen LLM-Proxy, Paginierung, Parallelität, eine Zahlungs-Saga und die Prüfung einer Webhook-Signatur.
• Script-Ressource und Endpunkte: Behandelt die sys-Struktur der Script-Ressource, die Spezifikation der HTTP-Endpunkte für Autorenschaft und Ausführung (/execute) sowie das Ausführungslog ScriptLog.

Wenn dies Ihr erstes Mal ist, empfehlen wir, ab dieser Seite in der Reihenfolge Wertausdrücke, dann Statement-Katalog zu lesen. Das Cookbook können Sie auch komplett durchsehen.