Statement-Katalog

Jedes Element des statements-Arrays ist ein einzelnes Statement. Dieses Dokument katalogisiert die Felder, das Verhalten und das Ergebnis aller 17 Statement-Typen. Jede Wertstelle folgt den Regeln der Wertausdrücke (Referenz, Literal, JsonLogic, Locale-Map).

Statement-Zusammenfassung

Zyklische Aufrufe sind auf 3 begrenzt. Die obigen ressourcenschreibenden Anweisungen (ResourceCreate, ResourceUpdate, ResourcePublish usw.) lösen Änderungsereignisse aus, und diese Ereignisse können über einen Webhook erneut ein Script ausführen. Eine solche Kette (Script → Ereignis → Webhook → Script → …) läuft höchstens 3-mal. Darüber hinaus bricht die Plattform sie automatisch ab, um Endlosschleifen zu verhindern.

Gemeinsame Felder

{ "type": "<StatementType>", "name": "<optional, im Script eindeutig>", /* ...typspezifische Felder... */ }

• type: Der Diskriminator. Einer der Werte aus der Tabelle oben (erforderlich).
• name: Optional. Wenn gesetzt, wird das Ergebnis unter /<name> an den Kontext gebunden, sodass spätere Statements es als { /<name>/... } referenzieren können. Weglassen, wenn das Ergebnis nicht verwendet wird.
• Regeln für Bindungsnamen: name (und das as bei Loop) ist ein Schlüssel, der direkt auf die Kontextwurzel gelegt wird, und wird daher beim Speichern validiert. Er darf kein leerer String sein und darf / und ~ nicht enthalten (muss als JSON-Pointer-Schlüssel verwendbar sein), darf nicht mit einer reservierten Wurzel (payload, vars, error) übereinstimmen und muss innerhalb eines Script eindeutig sein. Bei einem Verstoß wird das Speichern jeweils mit WGL400033 (Format), WGL400032 (reserviertes Wort) bzw. WGL400034 (Duplikat) abgelehnt.

Form der Entitätsreferenz

Entitätsreferenzen wie contentType und target werden zu einer einzigen Form vereinheitlicht: { "sys": { "id": <Wertausdruck> } }. Nur sys.id wird benötigt; der Zieltyp wird aus resource abgeleitet (sys.type und sys.targetType werden weggelassen).

• contentType.sys.id ist normalerweise ein Literal (z. B. "ct_post").
• target.sys.id ist normalerweise ein { /ptr }-Wertausdruck (zur Laufzeit aufgelöst, z. B. { /payload/sys/id }).

resource

Statements der Ressourcen-Familie geben die Zielart mit resource: "Content" | "Media" an.

Ressourcen schreiben

Jedes Schreib-Statement hat propagateEvents (Standard false). Wird es auf true gesetzt, gibt dieser Schreibvorgang sein eigenes EntityEvent aus (löst nachgelagerte Arbeit wie Suchindexierung und Webhooks aus). Der Standard gibt nichts aus (ein stiller System-Schreibvorgang).

ResourceCreate

Erstellt Content oder Media. Content und Media teilen sich das fields-Modell, und die Werte sind Locale-Maps.

• Media file: Der Wert von fields.file.{locale} ist eine Ingest-Anweisung { "source": <Wertausdruck>, "encoding": "url"|"base64" } (beide erforderlich). Ein Media-Schreibvorgang, der eine Datei enthält, ist nur Async (die Engine verarbeitet sie im Hintergrund inline und veröffentlicht anschließend; gilt für url und base64 gleichermaßen). Es lässt sich auch ein Media ohne Datei (fileless) erstellen. Bei publish:true, aber ohne Datei oder mit unfertiger Verarbeitung, tritt im Veröffentlichungsschritt ein Fehler auf; bei publish:false bleibt es Draft.
• Ergebnis (name-Bindung): die erstellte Ressource. { /<name>/sys/id }, { /<name>/fields/<field>/<locale> }.

// Content
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "{ /payload/fields/title }" } }, "publish": true, "name": "post" }
 
// Media. file ist eine Ingest-Anweisung (nur Async)
{ "type": "ResourceCreate", "resource": "Media",
  "fields": {
    "title": { "en-US": "{ /payload/fields/prompt }" },
    "file":  { "en-US": { "source": "{ /gen/body/data/0/url }", "encoding": "url" } }
  }, "name": "img" }

ResourceUpdate

Führt eine vollständige Ersetzung der Felder des Ziel-Content oder -Media durch (PUT). Was in fields übergeben wird, wird genau zum neuen Feldsatz, und alle hier nicht vorhandenen Felder und Locales werden gelöscht. Um nur einen Teil zu ändern, verwenden Sie ResourcePatch.

Wenn Sie bei einem Media Update verwenden, um nur die Metadaten zu ändern, fehlt file, und alle Dateien werden gelöscht (da es eine vollständige Ersetzung ist). Für partielle Änderungen verwenden Sie unbedingt ResourcePatch. Ein Update, das eine Datei enthält, ist nur Async.

{ "type": "ResourceUpdate", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "title": { "en-US": "Hello", "ko-KR": "안녕" }, "status": { "en-US": "published" } } }

ResourcePatch

Führt eine partielle Zusammenführung der Felder des Ziel-Content oder -Media durch (PATCH). Es überschreibt nur die in fields übergebenen Felder (und die darin enthaltenen Locales) und lässt alle nicht erwähnten Felder und Locales unverändert. Wertform, locale, version und publish sind identisch mit ResourceUpdate.

• Eine bestimmte Locale oder Datei löschen: Geben Sie als Wert ein literales null an. Beispiel: "title": { "fr-FR": null } (löscht den fr-FR-Titel), "file": { "en-US": null } (löscht die en-US-Datei). Ein Wertausdruck, der zur Laufzeit zu null ausgewertet wird, ist keine Löschung, sondern ein Fehler (nur ein literales null löscht).
• Übergeben Sie bei Media file eine Ingest-Anweisung, wird die Datei dieser Locale ersetzt (nur Async). Geben Sie keine Datei an, bleibt sie erhalten.

// nur +1 auf viewCount(en-US). title, andere Locales und alles Übrige bleiben unverändert
{ "type": "ResourcePatch", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "viewCount": { "en-US": { "+": [ "{ /payload/fields/viewCount }", 1 ] } } } }

ResourceDelete

Löscht das Ziel. Es können nur die Status Draft und Archived gelöscht werden. Bei Published oder Changed wird die Löschung abgelehnt, daher müssen Sie zuerst ResourceUnpublish ausführen (bei Media wird auch abgelehnt, solange die Datei verarbeitet wird (busy)). Es erfolgt kein Auto-Unpublish (wie bei CMA/ACMA).

{ "type": "ResourceDelete", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }

ResourcePublish, ResourceUnpublish, ResourceArchive, ResourceUnarchive

Steuert unabhängig den Veröffentlichungs- und Archivierungsstatus des Ziels. Alle vier haben dieselben Felder. Die Status-Vorbedingung jeder Operation ist identisch mit CMA/ACMA (publish ist von Archived aus nicht möglich und erfordert eine abgeschlossene Dateiverarbeitung; unpublish nur von Published/Changed; archive nur von Draft; unarchive nur von Archived).

{ "type": "ResourcePublish",   "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceUnpublish", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceArchive",   "resource": "Media",   "target": { "sys": { "id": "{ /m/sys/id }" } } }

Ressourcen lesen

Lese-Statements ändern den Status nicht (kein propagateEvents).

Alle drei Lese-Statements bestimmen mit from (optional, Standard Current), aus welchem gespeicherten Stand gelesen wird. Current ist der neueste Entwurf, den das Content Studio sieht (der Wert, den CMA/ACMA lesen); Published ist der veröffentlichte Snapshot (der Wert zum Zeitpunkt der letzten Veröffentlichung, den CDA/ACDA ausliefern).

ResourceFind und ResourcePageRead können darüber hinaus mit advanced (optional, Standard false) die Erweiterte Suche (Advanced Search) einschalten. Sie ist nur für Content, daher wird sie bei Media-Lesevorgängen ignoriert. Ist sie eingeschaltet, lassen sich in where die Operatoren regex, near und within sowie die Volltextsuche für Text verwenden (bei einem LongText-Feld mit aktivierter Volltextsuche findet eq auch Einträge, die den Wert enthalten, per Teil- und Ähnlichkeitstreffer), und order kann nach fields.* sortieren. Ist sie ausgeschaltet, werden diese drei Operatoren abgelehnt, eq auf Text ist exakte Übereinstimmung, und prefix sowie die Vergleichs- und Listenoperatoren funktionieren unabhängig von der erweiterten Suche. Ein soeben erstelltes oder geändertes Element benötigt einen kurzen Moment (etwa 1 Sekunde), bis es in der erweiterten Suche erscheint, und wird daher von einer unmittelbar folgenden Abfrage der erweiterten Suche möglicherweise noch nicht gefunden. Um ein soeben geschriebenes Element sofort zu lesen, verwenden Sie ResourceRead per id (aus dem primären Speicher, ohne diese Verzögerung) oder rufen Sie es über die sys.id ab, die der Schreibvorgang zurückgegeben hat.

In where und order schreiben Sie Benutzerfelder als fields.<field> (der bloße Feldname allein wird nicht erkannt). Auf fields.<field> wird automatisch die Standard-Locale des Space angewendet, daher fügen Sie keine Locale direkt an. fields.status und fields.slug in den Beispielen unten sind genau solche Abfragen über die Standard-Locale. Nur wenn Sie eine bestimmte (nicht standardmäßige) Locale ansteuern möchten, geben Sie sie mit fields.<field>.<locale> (z. B. fields.title.ko-KR) explizit an. sys.* (z. B. sys.createdAt) und createdBy (:self) schreiben Sie ohne fields. unverändert. Die ausführlichen Regeln finden Sie unter Locale bei where und order in den Wertausdrücken.

ResourceRead

Liest ein einzelnes Element per id (get-by-id). Das Ergebnis bindet die gesamte Ressource an den Namen.

• Ergebnis: Referenzieren Sie { /<name>/sys/id } und { /<name>/fields/<field>/<locale> } direkt (kein items/0 nötig).
• Wenn das Ziel nicht existiert, kommt es zu einem Fehler. Mit Try lässt sich das behandeln.

{ "type": "ResourceRead", "resource": "Content",
  "target": { "sys": { "id": "{ /payload/fields/orderId }" } }, "name": "order" }

ResourceFind

Liest das erste passende Einzelelement per Filter. Wenn es keines gibt, ist es null. Verwenden Sie es, um einen Datensatz über einen eindeutigen Geschäftsschlüssel (slug, email, sku) zu finden.

• Ergebnis: Bindet die erste passende Ressource an den Namen. Referenzieren Sie sie direkt als { /<name>/fields/<field>/<locale> }. Da sie null ist, wenn keine existiert, verzweigen Sie über die Existenz mit { "==": [ "{ /<name> }", null ] } (das typische find-then-upsert-Muster).

{ "type": "ResourceFind", "resource": "Content", "contentType": { "sys": { "id": "ct_article" } },
  "where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }, "name": "found" }

ResourcePageRead

Ein Abruf nach Filter, Sortierung und Seite.

• Ergebnis: { items, next }. { /<name>/items/0/... }, die nächste Seite ist { /<name>/next }.
• Für das Durchlaufen aller Elemente verwenden Sie Loop while "{ /vars/hasMore }" zusammen mit cursor und SetVar-Akkumulation (siehe Cookbook).

{ "type": "ResourcePageRead", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "where": { "fields.status": { "eq": "draft" } }, "order": "-sys.createdAt", "limit": 100, "name": "page" }

Extern

Http

Ruft einen externen HTTP-Endpunkt auf. Wenn Http vorhanden ist, muss executionMode Async sein (ExternalIo).

• Ergebnis: { status, body }. { /<name>/status }, { /<name>/body/... }.
• Maximale Antwortgröße: Der Antwort-Body ist maximal 10MiB groß. Wird dies überschritten, schlägt dieser Aufruf mit einer Ausnahme fehl und kann wie jeder andere Fehlschlag zur Laufzeit mit Try/catch behandelt werden (dies ist ein größenbasierter Fehlschlag und wird daher nicht durch ignoreStatusCode unterdrückt).

{ "type": "Http", "method": "POST", "url": "https://api.llm.com/v1/gen",
  "headers": [ { "key": "Authorization", "value": "Bearer sk-...", "secret": true } ],
  "body": { "prompt": "{ /payload/fields/prompt }" }, "timeoutMs": 15000, "retry": 1, "name": "resp" }

Variablen

SetVar

Deklariert oder aktualisiert eine Script-lokale, veränderbare Variable. Referenziert als { /vars/<var> } (JsonLogic hat keine Variablendeklaration, daher wird dies als Statement bereitgestellt).

{ "type": "SetVar", "var": "total", "value": 0 }
{ "type": "SetVar", "var": "total", "value": { "+": [ "{ /vars/total }", "{ /row/qty }" ] } }   // akkumulieren
{ "type": "SetVar", "var": "ids",   "value": { "merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] } }  // in Array sammeln

Ablaufsteuerung

If

Eine bedingte Verzweigung. condition ist JsonLogic, und ob etwas wahr oder falsch ist, folgt den Regeln unter Wahrheitswert.

{ "type": "If",
  "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" } } ],
  "else": [ /* ... */ ] }

Loop

Iteration. Wählen Sie einen Modus: over (foreach), while (Bedingung) oder for (Zählung). In jedem Modus erzwingt die Engine mit maxIterations eine Obergrenze (verhindert Endlosschleifen). Externe Aufrufe innerhalb von body (Http, Media-Datei-Ingest) sind verboten.

// foreach
{ "type": "Loop", "over": "{ /payload/fields/items }", "as": "item", "maxIterations": 100,
  "body": [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_item" } },
             "fields": { "name": { "en-US": "{ /item/name }" } } } ] }
 
// while
{ "type": "Loop", "while": "{ /vars/hasMore }", "maxIterations": 1000, "body": [ /* ... */ ] }
 
// counted (1..10 step 2)
{ "type": "Loop", "for": { "from": 1, "to": 10, "step": 2 }, "as": "i", "maxIterations": 100, "body": [ /* ... */ ] }

Parallel

Führt die Branches gleichzeitig aus und fährt nach dem Zusammenführen fort. Referenzen zwischen Branches sind nicht möglich (bei einer Abhängigkeit ordnen Sie sie sequenziell an).

{ "type": "Parallel", "branches": [
  [ { "type": "Http", "method": "GET", "url": "https://api.a.com/x", "name": "a" } ],
  [ { "type": "Http", "method": "GET", "url": "https://api.b.com/y", "name": "b" } ]
] }

Return

Dies ist das return aus der normalen Programmierung. Es gibt das Ergebnis des Script an den Aufrufer zurück und beendet an dieser Stelle normal.

• Wird Return nie erreicht, gibt es keinen Rückgabewert. Um ein Ergebnis zurückzugeben, geben Sie value explizit an.
• Da es sich um eine normale Beendigung handelt, nicht um eine Ausnahme oder einen throw, ist es kein catch-Ziel (auch innerhalb von Try beendet es das gesamte Script, aber finally wird dennoch ausgeführt).
• Auch ein Guard wird mit diesem Statement ausgedrückt: If kombiniert mit then:[Return] (bei Verletzung der Bedingung zurückgeben, sodass Nachfolgendes nicht ausgeführt wird). Das ist eine seiner mehreren Verwendungen.

{ "type": "Return", "value": { "orderId": "{ /order/sys/id }", "status": "paid" }, "statusCode": 201 }
{ "type": "Return", "value": { "reason": "payment failed" }, "isError": true, "statusCode": 402 }

Try

Ausnahmebehandlung.

• Wenn catch den Fehler behandelt, wird das Script nicht abgebrochen. Nur ein Fehlschlag ohne catch bricht das Script ab (einschließlich eines Kompensationsversuchs).
• Was als „Fehlschlag" gilt und die Grenzen der Kompensation (compensation) werden unter Ausführungssemantik, Einschränkungen und Sicherheit behandelt.

{ "type": "Try",
  "body":    [ { "type": "Http", "method": "POST", "url": "https://primary.api/gen", "name": "resp" },
               { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "{ /resp/body/text }" } } } ],
  "catch":   [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "Generierung fehlgeschlagen" }, "error": { "en-US": "{ /error/message }" } } } ],
  "finally": [ /* läuft immer */ ] }

Verwandte Dokumente

• Wertausdrücke: Die Wertregeln, denen alle oben genannten Felder folgen.
• Ausführungssemantik, Einschränkungen und Sicherheit: Ausführungsreihenfolge, Fehler, statische Einschränkungen und Sicherheit.
• Cookbook: Vollständige Beispiele, die diese Statements kombinieren.
• Script-Übersicht: Die oberste Struktur und die Ausführungsmodi.