Transactions

specdraftimplproposal

Atomare und gestapelte Transaktionen über mehrere Objektarten.

Umfang

Stellt eine einzelne Ressource POST /transactions bereit, die ein Transaktionsdokument mit einer oder mehreren insert-, replace-, update- oder delete-Aktionen über eine oder mehrere Objektarten der API entgegennimmt. Die kanonische Anfragecodierung ist application/ogc-tx+json; die Antwort ist application/json.

Es werden zwei Semantiken unterstützt: atomare Transaktionen führen alle Aktionen in einer einzigen Datenbanktransaktion aus (Rollback bei Fehlern), Batch-Transaktionen führen jede Aktion unabhängig aus und liefern Ergebnisse pro Aktion.

Zur Interoperabilität mit WFS 2.0-Produzenten kann der Baustein zusätzlich wfs:Transaction-XML-Payloads im atomaren Modus entgegennehmen.

Der Anfrage-Header Prefer wird gemäß RFC 7240 ausgewertet: return=representation (Standard), return=minimal oder return=none steuert den Umfang der Transaktionsantwort; handling=strict validiert jeden insert- und replace-Payload vor dem Schreiben gegen das Schema der Objektart (greift nur, wenn die Objektart eine Schema-Validierung konfiguriert hat \u2014 JSON Schema für GeoJSON-Payloads, XSD für GML-Payloads). respond-async wird mit 501 abgelehnt.

Der Anfrage-Header Content-Crs gibt das CRS der Koordinaten im Anfragetext an. Fehlt der Header, wird das Standard-CRS der API angenommen (CRS84, sofern nicht überschrieben); syntaktisch ungültige Werte oder ein nicht von der API unterstütztes CRS werden mit einem 4xx-Fehler abgelehnt.

Erfolgreiche und atomar fehlgeschlagene Antworten verwenden dieselbe Dokumentstruktur des Part-11-Transaction-Response (mit summary, den pro Aktion gegliederten Ergebnis-Arrays und gegebenenfalls einem exceptions[]-Array), so dass Clients zum Auswerten der Antwort nicht nach Statuscode unterscheiden müssen.

Limitierungen

Es gelten die folgenden Einschränkungen:

Provider und Anfragebereich:
Es werden nur Objektarten von einem SQL-Feature-Provider unterstützt, der Mutationen
erlaubt (datasetChanges.mode CRUD).
Asynchrone Transaktionen werden nicht unterstützt.
Antworten werden ausschließlich als JSON geliefert; die WFS
wfs:TransactionResponse-XML-Antwort wird nicht erzeugt.
wfs:Transaction-XML-Payloads werden nur im atomaren Modus akzeptiert.
Filter in update-, replace- und delete-Aktionen:
Filter sind auf die Auswahl von Objekten über deren Id beschränkt. JSON-Aktionen
akzeptieren entweder einen CQL2-Ausdruck der Form IN(<id-eigenschaft>, [...]) oder
<id-eigenschaft> = ..., wobei <id-eigenschaft> der Schemaname (bzw. Alias, falls
deklariert) der Eigenschaft der Objektart mit Rolle ID ist; andere CQL2-Prädikate
(Vergleichs-, Raum-, Zeit- oder boolesche Operatoren auf normalen Eigenschaften)
werden mit einem 4xx-Fehler abgelehnt.
wfs:Transaction-XML akzeptiert ausschließlich fes:ResourceId/@rid; andere
fes:Filter-Elementtypen werden nicht erkannt.
Semantik von update:
Eine update-Aktion führt eine eigenschaftsbezogene Teilaktualisierung an einem
vorhandenen Objekt in situ durch: jede angesprochene Eigenschaft wird in ein natives
SQL-UPDATE (für Spalten der Haupttabelle, einschließlich Geometrien) bzw. in ein
DELETE-mit-anschließendem-INSERT gegen die zugehörige Kindtabelle (für
VALUE_ARRAY- und OBJECT_ARRAY-Eigenschaften) übersetzt. Alle Anweisungen laufen auf
derselben Sitzungs-Verbindung wie der Rest der Transaktion, so dass ein update ein
Objekt verändern kann, das zuvor in derselben atomaren Anfrage per insert,
replace, update oder einer Junction-Mutation berührt wurde.
Die Menge der Eigenschaften, die per Teilaktualisierung geändert werden dürfen, wird
durch updatableProperties in der TRANSACTIONS-Konfiguration der Sammlung festgelegt;
eine Eigenschaft, deren kanonischer Pfad nicht in dieser Liste enthalten ist, wird mit
einem 4xx-Fehler abgelehnt. Die Standard-Whitelist ist leer und deaktiviert
Teil-Aktualisierungen für die Sammlung. Einträge sind die Schemabezeichner der
Eigenschaften, getrennt durch . (z.B. lifetime.end für eine verschachtelte Eigenschaft,
name für eine Eigenschaft der obersten Ebene).
Eigenschaftspfade werden gegen das Feature-Schema und das useAlias-Verhalten des
Eingabeformats aufgelöst. Pfade in name und delete einer JSON-Transaktion
verwenden die kanonische Punktnotation (Trenner .; das XPath-Schrägstrich-Format ist
wfs:ValueReference vorbehalten). Ein wfs:Update verwendet in wfs:ValueReference
die XPath-Form einschließlich des Objekttyp-Zwischenschritts (z.B.
lifetime/Lifetime/end); XML-Namensraum-Präfixe werden entfernt, nur lokale Namen und
die Pfadstruktur sind relevant.
Wählt der Filter mehrere Ids aus (z.B. IN(id, ['a','b']) oder mehrere
fes:ResourceId/@rid), wird derselbe Patch auf jede ausgewählte Objektinstanz
angewendet.
Ein fehlender Wert (<wfs:Property> ohne <wfs:Value> oder ein Eintrag in delete
einer JSON-Transaktion) leert die Eigenschaft: SQL-NULL für eine Spalte der
Haupttabelle bzw. ein leeres Ergebnis für VALUE_ARRAY / OBJECT_ARRAY (alle
Junction-Zeilen für die Eigenschaft werden entfernt, keine neuen eingefügt).
Geometrien: ein wfs:Update kann eine Geometrieeigenschaft setzen, indem das
entsprechende GML-Geometrieelement (z.B. <gml:Point>) in <wfs:Value> platziert
wird. Eine JSON-Transaktion verwendet ein GeoJSON-Geometrieobjekt als
Eigenschaftswert. Beide Formen nutzen denselben CRS-bewussten Encoder wie insert /
replace. Die Geometrieeigenschaft muss in der Haupttabelle der Objektart liegen;
Geometrien in Kindtabellen werden nicht unterstützt.
Wert-Arrays (VALUE_ARRAY): mehrere geschwisterliche <wfs:Property>-Elemente mit
derselben wfs:ValueReference werden auf der WFS-Seite zu einem Array zusammengefasst
(jeder Wert liefert ein Element). Eine JSON-Transaktion verwendet ein JSON-Array von
Skalaren. Das gesamte Array wird ersetzt.
Objekt-Arrays (OBJECT_ARRAY): ein wfs:Update setzt eine OBJECT_ARRAY-Eigenschaft,
indem ein oder mehrere objekttyp-Wrapperelemente in <wfs:Value> platziert werden
(eines pro Array-Element); eine JSON-Transaktion verwendet ein JSON-Array von
Objekten. Objektschlüssel bzw. die lokalen Namen der Kind-Elemente werden gegen das
Schema des Arrays auf dieselbe Weise wie skalare Pfade aufgelöst (id oder Alias gemäß
useAlias); unbekannte Schlüssel werden stillschweigend ignoriert. Das gesamte Array
wird ersetzt. Verschachtelte Objekt-Kinder innerhalb eines Array-Elements,
M:N-Junctions und FEATURE_REF-Arrays werden noch nicht unterstützt.

Konformitätsklassen

Der Baustein basiert auf den Konformitätsklassen "Transactions", "Atomic Semantics", "Batch Semantics", "JSON Encoding" und "Features" aus dem Entwurf von OGC API - Features - Part 11: Atomic and Batch Transactionsopen in new window.

Konfiguration

Optionen

Name	Default	Beschreibung	Typ	Seit
`buildingBlock`		Immer `TRANSACTIONS`.	string	v2.0
`enabled`	`false`	Soll der Baustein aktiviert werden?	boolean	v2.0
`atomic`	`true`	Schaltet die Konformitätsklasse für atomare Transaktionen frei. Anfragen ohne `semantic`-Parameter oder mit `semantic=atomic` werden in einer einzigen Datenbanktransaktion ausgeführt; jeder Fehler führt zum Rollback der gesamten Anfrage.	boolean	v4.8
`batch`	`true`	Schaltet die Konformitätsklasse für Batch-Transaktionen frei. Anfragen mit `semantic=batch` führen jede Aktion unabhängig aus und melden Ergebnisse pro Aktion, inkl. Ausnahmen bei Fehlern.	boolean	v4.8
`wfsTransaction`	`false`	Aktiviert die Dekodierung von WFS 2.0 `wfs:Transaction`-XML-Payloads bei `POST /transactions`. Nur zulässig, wenn `atomic` aktiv und der GML-Baustein aktiviert ist.	boolean	v4.8
`defaultSemantic`	`ATOMIC`	Semantik, die für Anfragen ohne explizite Angabe verwendet wird. Der Standard entspricht der Vorgabe aus OGC API Features Part 11.	string	v4.8
`maxActionsPerRequest`	`0`	Optionale Obergrenze für die Anzahl der Aktionen pro Anfrage. Der Wert `0` oder `null` deaktiviert die Begrenzung.	number	v4.8
`collectErrors`	`false`	Nur für atomare Semantik relevant. Wenn aktiviert, beendet eine fehlschlagende Aktion die Verarbeitung der Transaktion nicht: Die verbleibenden Aktionen werden trotzdem ausgeführt, alle Fehler werden gesammelt und in der Antwort gemeldet, während alle Änderungen dennoch zurückgerollt werden. Clients können so alle Fehler einer großen Transaktion in einem Durchgang beheben statt einen Fehler pro Versuch. Spätere Aktionen sehen die Änderungen früherer erfolgreicher Aktionen, nicht aber die fehlgeschlagener Aktionen \u2014 eine Aktion, die von einer fehlgeschlagenen Aktion abhängt, meldet daher in der Regel einen Folgefehler. Jede Aktion verursacht einen kleinen Mehraufwand in der Datenbank (einen Savepoint), der bei sehr großen Transaktionen spürbar sein kann. Erfordert einen SQL-Feature-Provider; andernfalls wird die Option ignoriert. Wenn deaktiviert, stoppt die Verarbeitung beim ersten Fehler, die verbleibenden Aktionen werden übersprungen und nur der erste Fehler wird gemeldet.	boolean	v4.8
`updatableProperties`	`[]`	Whitelist der Eigenschaften, die per Teil-Aktualisierung geändert werden dürfen (`wfs:Update`-Aktion einer `wfs:Transaction` bzw. `update`-Aktion einer JSON-Transaktion). Jeder Eintrag ist ein Eigenschaftspfad, dessen Segmente die kanonischen Schemabezeichner sind und durch `.` verbunden werden, z.B. `lifetime.end` für eine verschachtelte Eigenschaft oder `name` für eine Eigenschaft der obersten Ebene. Die Segmente verwenden immer die Schemabezeichner, unabhängig davon, ob für das Eingabeformat Aliase aktiviert sind. Eine Teil-Aktualisierung mit einem Pfad, der nicht in dieser Liste enthalten ist, wird mit einem 4xx-Fehler abgewiesen. Einträge auf API-Ebene gelten für jede Sammlung; Einträge auf einer Sammlung werden mit der API-Ebene zusammengeführt (Duplikate werden entfernt). Ist die effektive Liste für eine Sammlung leer, sind Teil-Aktualisierungen für diese Sammlung deaktiviert.	array	v4.8
`transactionSetup`	`null`	SQL-Anweisungen, die auf der Datenbanktransaktion direkt nach deren Beginn ausgeführt werden, bevor eine Aktion läuft. Typische Anwendungen sind transaktionsbezogene Einstellungen (`SET LOCAL \u2026`) oder der Aufruf einer Setup-Funktion. Jeder Eintrag ist eine einzelne Anweisung, die unverändert und in der angegebenen Reihenfolge auf der Transaktionsverbindung des Providers ausgeführt wird (nur PostgreSQL/PostGIS-Provider). Die Listen `always`, `strict` und `lenient` legen abhängig von der `Prefer: handling`-Präferenz der Anfrage fest, welche Anweisungen laufen. Eine fehlschlagende Anweisung bricht die Transaktion ab.	object	v4.8
`preCommit`	`null`	SQL-Anweisungen, die auf der Datenbanktransaktion direkt vor dem Commit ausgeführt werden. Typische Anwendungen sind Funktionen, die abgeleitete Daten aktualisieren oder die Konsistenz prüfen. Jeder Eintrag ist eine einzelne Anweisung, die unverändert und in der angegebenen Reihenfolge auf der Transaktionsverbindung des Providers ausgeführt wird (nur PostgreSQL/PostGIS-Provider). Die Listen `always`, `strict` und `lenient` legen abhängig von der `Prefer: handling`-Präferenz der Anfrage fest, welche Anweisungen laufen. Eine Anweisung, die einen Fehler auslöst, bricht die Transaktion ab und macht sie rückgängig; eine Anweisung, die nur eine Warnung ausgibt (`RAISE WARNING` / `RAISE NOTICE`), lässt die Transaktion committen, und die Warnung wird in der Antwort zurückgegeben. Der Fehler- bzw. Warnungstext wird unverändert in die Antwort übernommen (`exceptions` und `warnings`), und die Anweisungen laufen auf Datenbankebene ohne Zugriff auf die Aktionen der Anfrage. Daher sollten `RAISE`-Meldungen die betroffenen Objekte benennen \u2014 z.B. den Objektidentifikator enthalten \u2014, damit die Antwort auswertbar ist.	object	v4.8
`updatablePropertyPaths`			array	v2.0

Dieses Modul benötigt bzw. unterstützt keine zusätzlichen Konfigurationsdateien.

Beispiele


- buildingBlock: TRANSACTIONS
 enabled: true
 atomic: true
 batch: true
 wfsTransaction: false
 defaultSemantic: ATOMIC
 collectErrors: true

Per-collection partial-update whitelist (allows wfs:Update / JSON-transaction update
actions to set the listed scalar/datetime/geometry/VALUE_ARRAY/OBJECT_ARRAY properties):


collections:
 places:
   api:
     - buildingBlock: TRANSACTIONS
       updatableProperties:
         - location           # geometry on the main table
 buildings:
   api:
     - buildingBlock: TRANSACTIONS
       updatableProperties:
         - name               # top-level scalar
         - lifetime.end       # nested property
         - tags               # VALUE_ARRAY
         - addresses          # OBJECT_ARRAY

Transaction-lifecycle hooks (PostgreSQL/PostGIS providers). Statements are selected by the
request's Prefer: handling preference; a pre-commit error rolls the transaction back, a
pre-commit warning lets it commit and is returned in the response:


- buildingBlock: TRANSACTIONS
 transactionSetup:
   always:
     - SET LOCAL myapp.geometry_validation.enabled = true
   strict:
     - SET LOCAL myapp.geometry_validation.error_if_invalid = true
   lenient:
     - SET LOCAL myapp.geometry_validation.error_if_invalid = false
 preCommit:
   always:
     - SELECT myapp.update_derived_data()
   strict:
     - SELECT myapp.assert_consistency()

# Transactions

# Umfang

# Limitierungen

# Konformitätsklassen

# Konfiguration

# Optionen

# Beispiele