Transformコネクタ

概要

Transformコネクタは、ルールのリストを評価することによりペイロードフィールドを追加または置換します。各ルールは、JSONPath、Goのtext/template、または静的リテラルのいずれかの式型を使用して1つの出力キーを生成します。

コネクタタイプ: MeddleTransform

設定

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

設定パラメータ

rules（必須、最小1）：変換ルールの順序付き配列
dropOriginal: trueの場合、ルール出力のみが発行され、ソースペイロードは破棄されます。デフォルトはfalse — ソースフィールドが保持され、ルール出力がそれらを上書きします。

ルールフィールド

outputKey（必須）：ルールが書き込むペイロードキー
type（必須）：jsonpath、template、またはstatic
expression（必須）：型固有の式

JSONPathルール

type: "jsonpath"は、ペイロード（内部でJSONにマーシャル化）に対してJSONPath式を評価します。ネストされた値の抽出に使用します。

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

一般的なパターン：

$.field                    – トップレベルフィールド
$.sensor.temperature       – ネストフィールド
$.metrics[0].value         – 配列の最初の要素
$.metrics[*].name          – 配列射影

テンプレートルール

type: "template"は、ペイロードに対してGoのtext/templateを実行します。ペイロードフィールドは{{ .field }}としてアクセスできます。結果は常に文字列です。

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

{{ .temperature }}                                              – 置換
{{ if gt .pressure 100.0 }}HIGH{{ else }}OK{{ end }}            – 条件付き
Sensor {{ .id }} reports {{ printf "%.2f" .value }}             – フォーマット

静的ルール

type: "static"は、すべてのペイロードでoutputKeyにリテラルのexpression文字列を書き込みます。タグ、ソースマーカー、またはパイプラインIDに使用します。

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

Drop Original

dropOriginal: trueの場合、コネクタはルール出力のみを発行し、すべての入力フィールドを破棄します。これを使用してペイロードを最小限の形状に投影します。

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

ユースケース

ダウンストリームコネクタ用にネストされたフィールドをトップレベルに抽出
通知用に人間が読みやすい要約文字列を構築
パイプラインまたはソース識別子でペイロードをタグ付け
冗長なプロトコルペイロードをスリムなダウンストリームスキーマに再構築

例: 混合ルールタイプ

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

alert_textがdevice_idを参照していることに注意してください — 同じTransformパス内で前のルールの出力は後のルールから見えないため、{{ .device_id }}は、上流に既に存在する場合のみ、元のペイロードキーを参照します。段階的な合成が必要な場合は2つのTransformコネクタをチェーンします。

ベストプラクティス

構造化された値を抽出する場合はJSONPathを使用。文字列構成にはtemplateを使用。定数にはstaticを使用
ロジックが抽出またはフォーマットのみの場合はScriptよりもTransformを優先 — より高速で監査しやすい
厳格なダウンストリームスキーマを強制するにはdropOriginal: trueを使用
JSONPath式を事前に検証 — 無効なパスはエラーチャネルでランタイムエラーとして表面化します