JSON-Wert Projektion

Siehe auch: Check JSONPath (Plugin)

Projektion - Kurzfassung
Zweck: Dient zum Auflösen von Werten mit einem bestimmten Ergebnistyp aus einem im JSON-Format definierten Datenobjekt über einen innerhalb der Projektion in JSONPath-Syntax statisch definierten JSON-Pfad.
Tooltip
Verwendung: Auf über eine Projektion bereitgestellten JSON-Daten (bzw. einem JSON-String) wird der JSON Pfad (JSONPath-Ausdruck) angewendet, um einen Rückgabewert vom Typ Ergebniswert zu ermitteln.
Parameter:
Name definiert optional den Titel einer Ausgabespalte (soweit relevant). Per Standard erscheint als Spaltenname der Name für die konfigurierte Projektion mit dem Präfix “json value of “.
Als Projektion wird eine Projektion erwartet, die JSON-Daten (z. B. aus einem Beliebiger Typ-Feld) oder Text mit entsprechender Syntax liefert.
Der JSON Pfad definiert durch einen statischen JSONPath-Ausdruck, wie aus den durch die Projektion gelieferten Daten ein Rückgabewert ermittelt werden soll. Im Ausdruck symbolisiert $ den Rückgabewert als Ganzes.
Der Ergebnistyp (Standard: String) muss in Abstimmung mit dem JSON Pfad unter Berücksichtigung der SQL/JSON-Syntax im verwendeten Datenbanksystems ausgewählt werden, um den gewünschten Wert aufzulösen.
Hinweis: Der Wertauflöser zielt in erster Linie auf die Gewinnung eines Einzelwerts ab, der abhängig vom Datenbanksystem ggf. auch aus einem Array “herausgesucht” werden kann. Ein in der Datenquelle als Wert vorliegendes Array kann mit dem Ergebnistyp “Objekt” i. d. R. ebenfalls zurückgegeben werden. Der Versuch über den JSON Pfad ein Array von Einzelwerten als Rückgabewert zu gewinnen gelingt dagegen nur in Ausnahmefällen.

Eine JSON-Wert Projektion dient zum Auflösen von Werten mit einem bestimmten Ergebnistyp aus einem im JSON-Format definierten Datenobjekt über einen innerhalb der Projektion in JSONPath-Syntax statisch definierten JSON-Pfad.

WICHTIG Welche Funktionalität die JSON-Wert Projektion im Einzelfall konkret bereitstellen kann, hängt letztendlich immer davon ab, welche Möglichkeiten das für die Lobster Data Platform genutzten Datenbanksystem für diesen Zweck beinhaltet und wie die generische Konfiguration darauf intern abgebildet ist. Primär soll die JSON-Wert Projektion den Zugriff auf einen Wert aus der JSON-Datenquelle ermöglichen. Ob bzw. unter welchen Bedingungen der JSONPath-Ausdruck ein Array von mehreren Werten liefern kann, hängt vom Datenbanksystem (und ggf. auch dessen Version) ab.

Konfiguration

Parameter	Typ	Beschreibung
Name	`String`	Der optionale Parameter Name kann verwendet werden, um der Projektion einen (Alias-)Namen zuzuweisen. Wenn kein Name angegeben ist, wird als Spaltenname (sofern relevant) der Name (bzw. der Alias) für die konfigurierte Projektion mit dem Präfix “`json value of` “ verwendet.
Projektion	Entität (Projektion)	Der Parameter Projektion definiert die Datenquelle, auf die der JSON Pfad angewendet werden soll, um einen Wert zu extrahieren. Als Datenquelle werden mehr oder weniger komplexe JSON-Daten erwartet, die wahlweise als Text (`String`) oder in einem JSON-spezifischen Feld (z. B. Beliebiger Typ-Feld für Eigene Typdefinitionen) bereitgestellt werden können. HINWEIS Typischerweise wird eine Feldprojektion eingesetzt, um Quelldaten aus der Datenstruktur einer in der Lobster Data Platform persistierten Entität in eine Abfrage einzubinden. Allerdings kann auch eine Literale Projektion nützlich sein, um im Rahmen von Tests für den “passenden” JSON-Pfad einen statischen Beispieltext als Datenquelle zu definieren oder über Wertauflöser Daten aus dem (z. B. Sitzungsbasiert (Wertauflöser)) einzusteuern, die über den JSON-Pfad ausgewertet werden sollen.
JSON Pfad	`String`	Der Parameter JSON Pfad enthält einen statischen Text, der in JSONPath-Syntax definiert, welche Information aus dem Rückgabewert der Projektion aufgelöst werden soll. Das Symbol `$` — in der Regel am Anfang des JSONPath-Ausdrucks — steht für den Rückgabewert der Projektion. WICHTIG Ob ein bestimmter Ausdruck funktioniert, hängt letztendlich vom verwendeten Datenbanksystem ab, auf dem der Lobster Data Platform-Server betrieben wird. Unter Umständen kann nicht das komplette JSONPath-Repertoire genutzt werden oder es ist eine spezifische Anpassung der Notation erforderlich. Ob ein JSON-Pfad den erwarteten Wert liefert, kann außerdem vom ausgewählten Ergebnistyp abhängen, da dieser die eventuell die Auswahl der verwendeten JSON-Funktion in der Syntax für das verwendete Datenbanksystem bestimmt.
Ergebnistyp	Klasse (Datentyp)	Im Auswahlfeld/Combobox-Element für den Ergebnistyp sollte passend zum erwarteten Ergebnis des JSONPath-Ausdrucks eine der folgenden Optionen ausgewählt werden: `String` (Standard) für Textwerte oder andere skalare Werte, die als String interpretiert werden sollen `Boolean` für Wahrheitswerte (`true` oder `false`) “Objekt” (`Object`) für alle anderen Typen

Beispiel

Einfacher Anwendungsfall: Klasse eines eingebetteten Objekts auswerten

Einige Entitätstypen, die die Lobster Data Platform systemseitig vordefiniert, verfügen über Felder denen eingebettete Objekte unterschiedlicher Klassen zugeordnet werden können:

Der über den Menüpunkt API-Manager verwaltete Entitätstyp “API” (RestApiDefinition) beinhaltet ein Feld “API” (api), das wahlweise eine Konfiguration des Typs REST API oder MCP-Server enthält.

Da das System nur eine gemeinsame Übersicht für den Entitätstyp “API” (RestApiDefinition) bereitstellt, sollen in dieser Liste die MCP-Server-Konfigurationen per Zeilenformatierung hervorgehoben werden.

Der folgende Screenshot zeigt das gewünschte Ergebnis im API-Manager:

Zusätzlich zur Unterscheidung per Icon (s. API-Spalte) erscheinen die MCP-Server-Konfigurationen mit neongrünem Hintergrund.

Konfiguration:

Eine spezifische Zeilenformatierung kann im Kontext der Client-Einstellungen für eine Liste (Ribbon: Einstellungen / Liste /Bearbeiten) definiert werden (Details s. Zeilenformatierung in Datengrids).

Ob ein bestimmtes Zeilenformat einer Listenzeile zugewiesen werden soll oder nicht, bestimmt dabei die “Bedingung”, die als Einschränkung (s. Einschränkungen) definiert werden muss.

Der Rückgabewert aus einer Feldprojektion für das Feld “API” (API) kann daher nicht einfach einer Typprüfung unterzogen werden, was im Kontext einer Regel (s. Regeln und Werte) naheliegend und komfortabel wäre.

Da im Feld “API” (API) alle spezifischen Details zur gewählten API-Klasse als JSON-Daten gespeichert werden, kann man stattdessen allerdings — ähnlich bequem -- das class-Feld des API-Objekts auswerten.

{
	"class": "de.lobster.scm.api.mcp.McpRestApi",
	"baseUri": "myFancyMcp",
	...
	"tools": [ ... ]
}

Auf der linken Seite der oben abgebildeten Feld Einschränkung kommt die JSON-Wert Projektion zum Einsatz:
- Als Projektion dient eine Feldprojektion auf das Feld “API” (api).
- Der JSON-Pfad $.class greift direkt auf den Wert der class-Eigenschaft des Datenobjekts im Rückgabewert der Projektion ($) zu.
- Der Ergebnistyp String passt hier für den fully qualified class name als Prüfwert.
Auf der rechten Seite wird der Klasse-Wertauflöser verwendet, um die Klasse “MCP-Server” (McpRestApi) als statischen Vergleichswert festzulegen.
HINWEIS Aus dem Objekt des Typs “Klasse” (class) wird für den Vergleich automatisch der fully qualified class name als String-Abbild herangezogen, der im Label des Auswahlfeld/Combobox-Elements in Klammern erscheint.

ANMERKUNG Die JSON-Wert Projektion wird als Basis für die Spalte “API” (api) der Klasse “API” (RestApiDefinition) auch systemseitig herangezogen. Dies wird z. B. deutlich, wenn man einen Filter für diese Spalte setzt und dann mit gehaltener Umschalt-Taste den Ribbon Button “Liste / Suchen” betätigt, um die Tupel-Suche hinter der aktuellen Übersicht in die Zwischenablage zu kopieren:

Wenn man anschließend die Tupel-Suche aus der Zwischenablage in den Abfragekonfigurator einfügt, erscheint dort in der Bedingung (wie auch unter Projektionen) eine entsprechende JSON-Wert Projektion mit dem Namen api→class.