Transform-Konnektor

Übersicht

Der Transform-Konnektor fügt Payload-Felder hinzu oder ersetzt sie, indem eine Liste von Regeln ausgewertet wird. Jede Regel produziert einen Ausgabe-Schlüssel unter Verwendung eines von drei Ausdruckstypen: JSONPath, Go-text/template oder ein statisches Literal.

Konnektor-Typ: MeddleTransform

Konfiguration

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": false,
    "rules": [
      { "outputKey": "temperature",  "type": "jsonpath", "expression": "$.sensor.temperature" },
      { "outputKey": "summary",      "type": "template", "expression": "{{ .sensor_id }}: {{ .status }}" },
      { "outputKey": "data_source",  "type": "static",   "expression": "edge-gateway-01" }
    ]
  }
}

Konfigurationsparameter

rules (erforderlich, min 1): Geordnetes Array von Transformationsregeln
dropOriginal: Bei true werden nur die Regel-Ausgaben ausgegeben; die Quell-Payload wird verworfen. Standard false — Quellfelder bleiben erhalten und Regel-Ausgaben überlagern sie.

Regelfelder

outputKey (erforderlich): Payload-Schlüssel, in den die Regel schreibt
type (erforderlich): jsonpath, template oder static
expression (erforderlich): Typspezifischer Ausdruck

JSONPath-Regeln

type: "jsonpath" wertet einen JSONPath-Ausdruck gegen die Payload aus (intern in JSON gemarshallt). Verwenden Sie dies zum Extrahieren verschachtelter Werte.

{ "outputKey": "first_metric", "type": "jsonpath", "expression": "$.metrics[0].value" }

Häufige Muster:

$.field                    – Top-Level-Feld
$.sensor.temperature       – verschachteltes Feld
$.metrics[0].value         – erstes Array-Element
$.metrics[*].name          – Array-Projektion

Template-Regeln

type: "template" führt ein Go-text/template gegen die Payload aus. Payload-Felder sind als {{ .field }} zugänglich. Das Ergebnis ist immer ein String.

{ "outputKey": "label", "type": "template", "expression": "{{ .device }}/{{ .channel }}" }

{{ .temperature }}                                              – Substitution
{{ if gt .pressure 100.0 }}HIGH{{ else }}OK{{ end }}            – Bedingung
Sensor {{ .id }} reports {{ printf "%.2f" .value }}             – Formatierung

Statische Regeln

type: "static" schreibt den literalen expression-String bei jeder Payload an outputKey. Verwendung für Tags, Quellmarker oder Pipeline-IDs.

{ "outputKey": "source", "type": "static", "expression": "field-gateway" }

Drop Original

Bei dropOriginal: true gibt der Konnektor nur die Regel-Ausgaben aus und verwirft jedes Eingabefeld. Verwenden Sie dies, um eine Payload auf eine minimale Form zu projizieren.

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": true,
    "rules": [
      { "outputKey": "ts",    "type": "jsonpath", "expression": "$.timestamp" },
      { "outputKey": "value", "type": "jsonpath", "expression": "$.metrics[0].value" }
    ]
  }
}

Anwendungsfälle

Ein verschachteltes Feld extrahieren auf die oberste Ebene für nachgelagerte Konnektoren
Eine menschenlesbare Zusammenfassung erstellen für Benachrichtigungen
Payloads kennzeichnen mit einer Pipeline- oder Quellkennung
Eine ausführliche Protokoll-Payload umformen in ein schlankes nachgelagertes Schema

Beispiel: Gemischte Regeltypen

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": false,
    "rules": [
      { "outputKey": "device_id",   "type": "jsonpath", "expression": "$.metadata.deviceId" },
      { "outputKey": "temperature", "type": "jsonpath", "expression": "$.readings.temp" },
      { "outputKey": "alert_text",  "type": "template", "expression": "Device {{ .device_id }} at {{ .temperature }}°C" },
      { "outputKey": "env",         "type": "static",   "expression": "production" }
    ]
  }
}

Beachten Sie, dass alert_text device_id referenziert — Ausgaben früherer Regeln sind späteren Regeln innerhalb desselben Transform-Durchlaufs nicht sichtbar, sodass {{ .device_id }} nur auf den ursprünglichen Payload-Schlüssel verweist, wenn er bereits vorgelagert existiert. Verketten Sie zwei Transform-Konnektoren, wenn Sie eine gestufte Komposition benötigen.

Best Practices

Verwenden Sie JSONPath beim Extrahieren strukturierter Werte; verwenden Sie Template für die String-Komposition; verwenden Sie static für Konstanten
Bevorzugen Sie Transform gegenüber Script, wenn die Logik nur Extraktion oder Formatierung ist — er ist schneller und einfacher zu prüfen
Verwenden Sie dropOriginal: true, um ein strenges nachgelagertes Schema durchzusetzen
Validieren Sie JSONPath-Ausdrücke im Voraus — ungültige Pfade erscheinen als Laufzeitfehler auf dem Fehlerkanal