Connettore Protocol Translator

Panoramica

Il connettore Protocol Translator decodifica un payload da un formato strutturato in una map chiave-valore piatta, opzionalmente rinomina le chiavi, quindi codifica il risultato in un formato di destinazione diverso. È il bridge canonico tra protocolli industriali e stadi a valle JSON-nativi.

Tipo Connettore: MeddleProtocolTranslator

Formati Supportati

• flat-json — Map chiave/valore semplice ({ "temp": 25.5, "press": 101.3 })
• nested-json — Oggetto annidato; decodificato per dot-flattening, codificato per dot-unflattening ({ "sensor": { "temp": 25.5 } } ↔ { "sensor.temp": 25.5 })
• sparkplugb — Forma Eclipse Sparkplug B: un array metrics di voci { "name": "...", "value": ... }
• opcua-json — JSON OPC-UA per nodo: ogni chiave di primo livello mappa a { "value": ..., "sourceTimestamp": ... }

sourceFormat e targetFormat devono differire.

Configurazione

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

Il connettore prima decodifica le metriche Sparkplug B in { "Temperature/Zone1": 25.5, "Pressure/Main": 101.3 }, quindi rinomina le chiavi secondo keyMappings, infine emette il JSON flat.

Parametri di Configurazione

• sourceFormat (richiesto): Uno tra flat-json, nested-json, sparkplugb, opcua-json
• targetFormat (richiesto): Uno tra flat-json, nested-json, sparkplugb, opcua-json (deve differire da sourceFormat)
• keyMappings: Map opzionale di oldKey -> newKey. Le chiavi non presenti nella map passano invariate.

Pipeline di Traduzione

1. Decode — Il payload sorgente viene normalizzato in una map[string]any piatta.
   • flat-json copia il payload così com’è
   • nested-json appiattisce gli oggetti annidati con . come separatore
   • sparkplugb estrae ogni metrics[i].value chiavato da metrics[i].name
   • opcua-json estrae il campo value di ogni nodo di primo livello
2. Rename — Applica keyMappings per rinominare le chiavi.
3. Encode — Rimodella la map flat nel formato di destinazione.
   • flat-json scrive la map direttamente
   • nested-json espande le chiavi delimitate da . in oggetti annidati
   • sparkplugb avvolge ogni coppia chiave/valore come { "name": k, "value": v } in un array metrics
   • opcua-json avvolge ogni valore come { "value": v, "sourceTimestamp": null }

Casi d’Uso

1. Sparkplug B a JSON flat per ingestione in database che si aspettano chiavi semplici
2. OPC-UA JSON a JSON flat per rimuovere i metadati dei nodi prima dell’alerting
3. JSON flat a Sparkplug B quando si pubblica su un broker MQTT conforme a Sparkplug
4. Flattening di JSON annidato per connettori a valle che si aspettano uno spazio chiavi piatto

Esempio: OPC-UA a JSON Flat

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

Input:

{
  "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" }
}

Output:

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

Esempio: JSON Flat a JSON Annidato

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

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

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

Migliori Pratiche

• Usa keyMappings per allineare i nomi di tag a monte con le convenzioni di schema a valle in un singolo step
• Combina con Transform per cambiamenti a livello di valore (formule, coercizione di tipo) che vanno oltre la rinomina delle chiavi
• I payload Sparkplug B devono contenere un array metrics di oggetti con campi name e value — valida a monte se la sorgente è inaffidabile
• Il round-trip flat-json -> opcua-json -> flat-json è supportato, ma sourceTimestamp viene impostato a null in codifica

Connettori Correlati

• Transform - JSONPath, template ed estrazione di valori statici
• Reshape - Rinomina diretta di chiavi senza cambio di formato
• File Format - Parsing di CSV e XML