ldproxy

Transactions

specdraftimplcandidate

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

NameDefaultBeschreibungTypSeit
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
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.9
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

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
ImpressumDatenschutzerklärung