Connettore Transform

Panoramica

Il connettore Transform aggiunge o sostituisce campi del payload valutando una lista di regole. Ogni regola produce una chiave di output utilizzando uno tra tre tipi di espressione: JSONPath, text/template di Go o un letterale statico.

Tipo Connettore: MeddleTransform

Configurazione

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

Parametri di Configurazione

• rules (richiesto, min 1): Array ordinato di regole di trasformazione
• dropOriginal: Quando true, vengono emessi solo gli output delle regole; il payload sorgente viene scartato. Default false — i campi sorgente vengono preservati e gli output delle regole li sovrappongono.

Campi della Regola

• outputKey (richiesto): Chiave del payload su cui la regola scrive
• type (richiesto): jsonpath, template, o static
• expression (richiesto): Espressione specifica per tipo

Regole JSONPath

type: "jsonpath" valuta un’espressione JSONPath contro il payload (serializzato internamente in JSON). Usalo per estrarre valori annidati.

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

Pattern comuni:

$.field                    – campo di primo livello
$.sensor.temperature       – campo annidato
$.metrics[0].value         – primo elemento dell'array
$.metrics[*].name          – proiezione di array

Regole Template

type: "template" esegue un text/template Go contro il payload. I campi del payload sono accessibili come {{ .field }}. Il risultato è sempre una stringa.

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

{{ .temperature }}                                              – sostituzione
{{ if gt .pressure 100.0 }}HIGH{{ else }}OK{{ end }}            – condizionale
Sensor {{ .id }} reports {{ printf "%.2f" .value }}             – formattazione

Regole Static

type: "static" scrive la stringa expression letterale su outputKey per ogni payload. Usalo per tag, marcatori di sorgente o ID di pipeline.

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

Drop Original

Quando dropOriginal: true, il connettore emette solo gli output delle regole e scarta ogni campo di input. Usalo per proiettare un payload in una forma minima.

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

Casi d’Uso

1. Estrarre un campo annidato al livello superiore per connettori a valle
2. Costruire una stringa di riepilogo leggibile per notifiche
3. Marcare i payload con un identificatore di pipeline o sorgente
4. Rimodellare un payload di protocollo verboso in uno schema a valle snello

Esempio: Tipi di Regole Misti

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

Nota che alert_text fa riferimento a device_id — gli output delle regole precedenti non sono visibili alle regole successive all’interno dello stesso passaggio Transform, quindi {{ .device_id }} si riferisce alla chiave del payload originale solo se esiste già a monte. Concatena due connettori Transform quando hai bisogno di composizione a stadi.

Migliori Pratiche

• Usa JSONPath quando estrai valori strutturati; usa template per la composizione di stringhe; usa static per costanti
• Preferisci Transform a Script quando la logica è solo estrazione o formattazione — è più veloce e più facile da auditare
• Usa dropOriginal: true per imporre uno schema a valle strict
• Valida anticipatamente le espressioni JSONPath — i percorsi non validi emergono come errori runtime sul canale di errore

Connettori Correlati

• Reshape - Rinomina diretta di chiavi
• Script - Lua in sandbox per logica complessa
• Filter - Whitelist/blacklist di chiavi
• Validation - Imponi tipi e range di campi