Protocol Translator-Konnektor

Übersicht

Der Protocol Translator-Konnektor decodiert eine Payload von einem strukturierten Format in eine flache Schlüssel-Wert-Map, benennt optional Schlüssel um und codiert das Ergebnis dann in ein anderes Zielformat. Es ist die kanonische Brücke zwischen industriellen Protokollen und JSON-nativen nachgelagerten Stufen.

Konnektor-Typ: MeddleProtocolTranslator

Unterstützte Formate

• flat-json — Einfache Schlüssel/Wert-Map ({ "temp": 25.5, "press": 101.3 })
• nested-json — Verschachteltes Objekt; durch Punkt-Abflachung dekodiert, durch Punkt-Aufhebung codiert ({ "sensor": { "temp": 25.5 } } ↔ { "sensor.temp": 25.5 })
• sparkplugb — Eclipse-Sparkplug-B-Form: ein metrics-Array von { "name": "...", "value": ... }-Einträgen
• opcua-json — Pro-Knoten-OPC-UA-JSON: jeder Top-Level-Schlüssel wird auf { "value": ..., "sourceTimestamp": ... } abgebildet

sourceFormat und targetFormat müssen sich unterscheiden.

Konfiguration

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "sparkplugb",
    "targetFormat": "flat-json",
    "keyMappings": {
      "Temperature/Zone1": "temperature_zone_1",
      "Pressure/Main":     "pressure_main"
    }
  }
}

Der Konnektor decodiert zuerst Sparkplug B-Metrics in { "Temperature/Zone1": 25.5, "Pressure/Main": 101.3 }, benennt dann Schlüssel gemäß keyMappings um und gibt dann das flache JSON aus.

Konfigurationsparameter

• sourceFormat (erforderlich): Einer von flat-json, nested-json, sparkplugb, opcua-json
• targetFormat (erforderlich): Einer von flat-json, nested-json, sparkplugb, opcua-json (muss sich von sourceFormat unterscheiden)
• keyMappings: Optionale Map von oldKey -> newKey. Schlüssel, die nicht in der Map vorhanden sind, werden unverändert durchgereicht.

Übersetzungs-Pipeline

1. Decode — Quell-Payload wird in eine flache map[string]any normalisiert.
   • flat-json kopiert die Payload unverändert
   • nested-json flacht verschachtelte Objekte mit . als Trennzeichen ab
   • sparkplugb extrahiert jedes metrics[i].value, gekennzeichnet nach metrics[i].name
   • opcua-json extrahiert das value-Feld jedes Top-Level-Knotens
2. Rename — keyMappings anwenden, um Schlüssel umzubenennen.
3. Encode — Die flache Map in das Zielformat umformen.
   • flat-json schreibt die Map direkt
   • nested-json hebt .-getrennte Schlüssel in verschachtelte Objekte auf
   • sparkplugb umhüllt jeden Schlüssel/Wert als { "name": k, "value": v } in einem metrics-Array
   • opcua-json umhüllt jeden Wert als { "value": v, "sourceTimestamp": null }

Anwendungsfälle

1. Sparkplug B zu flachem JSON für die Aufnahme in Datenbanken, die einfache Schlüssel erwarten
2. OPC-UA JSON zu flachem JSON, um Knoten-Metadaten vor der Alarmierung zu entfernen
3. Flaches JSON zu Sparkplug B beim Veröffentlichen an einen Sparkplug-konformen MQTT-Broker
4. Verschachtelte JSON-Abflachung für nachgelagerte Konnektoren, die einen flachen Schlüsselraum erwarten

Beispiel: OPC-UA zu flachem JSON

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "opcua-json",
    "targetFormat": "flat-json"
  }
}

Eingabe:

{
  "ns=2;s=Temp":  { "value": 25.5, "sourceTimestamp": "2025-01-01T12:00:00Z" },
  "ns=2;s=Press": { "value": 101.3, "sourceTimestamp": "2025-01-01T12:00:00Z" }
}

Ausgabe:

{
  "ns=2;s=Temp":  25.5,
  "ns=2;s=Press": 101.3
}

Beispiel: Flaches JSON zu verschachteltem JSON

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "flat-json",
    "targetFormat": "nested-json",
    "keyMappings": {
      "temp": "sensor.temperature",
      "press": "sensor.pressure"
    }
  }
}

Eingabe: { "temp": 25.5, "press": 101.3 }

Ausgabe: { "sensor": { "temperature": 25.5, "pressure": 101.3 } }

Best Practices

• Verwenden Sie keyMappings, um vorgelagerte Tag-Namen in einem einzigen Schritt an nachgelagerte Schemakonventionen anzupassen
• Kombinieren Sie mit Transform für wertebezogene Änderungen (Formeln, Typkonvertierung), die über das Umbenennen von Schlüsseln hinausgehen
• Sparkplug B-Payloads müssen ein metrics-Array von Objekten mit name- und value-Feldern enthalten — vorgelagert validieren, wenn die Quelle unzuverlässig ist
• Round-Tripping flat-json -> opcua-json -> flat-json wird unterstützt, aber sourceTimestamp wird beim Codieren auf null gesetzt

Verwandte Konnektoren

• Transform - JSONPath, Template und statische Wertextraktion
• Reshape - Direkte Schlüssel-Umbenennung ohne Formatänderung
• File Format - CSV- und XML-Parsing