Protocol Translatorコネクタ

概要

Protocol Translatorコネクタは、ペイロードをある構造化形式からフラットなキー・バリューマップにデコードし、オプションでキーの名前を変更し、結果を別のターゲット形式にエンコードします。産業プロトコルとJSONネイティブのダウンストリームステージ間の正規ブリッジです。

コネクタタイプ: MeddleProtocolTranslator

サポートされる形式

flat-json — プレーンなキー/値マップ（{ "temp": 25.5, "press": 101.3 }）
nested-json — ネストオブジェクト。ドットフラット化によりデコードされ、ドットアンフラット化によりエンコードされます（{ "sensor": { "temp": 25.5 } } ↔ { "sensor.temp": 25.5 }）
sparkplugb — Eclipse Sparkplug B形式：{ "name": "...", "value": ... }エントリのmetrics配列
opcua-json — ノードごとのOPC-UA JSON：各トップレベルキーは{ "value": ..., "sourceTimestamp": ... }にマップ

sourceFormatとtargetFormatは異なる必要があります。

設定

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

コネクタはまずSparkplug Bメトリクスを{ "Temperature/Zone1": 25.5, "Pressure/Main": 101.3 }にデコードし、次にkeyMappingsに従ってキーをリネームし、最後にフラットJSONを発行します。

設定パラメータ

sourceFormat（必須）：flat-json、nested-json、sparkplugb、opcua-jsonのいずれか
targetFormat（必須）：flat-json、nested-json、sparkplugb、opcua-jsonのいずれか（sourceFormatと異なる必要があります）
keyMappings: oldKey -> newKeyのオプションマップ。マップに存在しないキーは変更されずにパススルーされます。

変換パイプライン

デコード — ソースペイロードはフラットなmap[string]anyに正規化されます。
- flat-jsonはペイロードをそのままコピー
- nested-jsonは.を区切り文字としてネストオブジェクトをフラット化
- sparkplugbは各metrics[i].valueをmetrics[i].nameをキーとして抽出
- opcua-jsonは各トップレベルノードのvalueフィールドを抽出
リネーム — keyMappingsを適用してキーをリネーム。
エンコード — フラットマップをターゲット形式に再構成。
- flat-jsonはマップを直接書き込み
- nested-jsonは.区切りキーをネストオブジェクトにアンフラット化
- sparkplugbは各キー/値をmetrics配列内の{ "name": k, "value": v }としてラップ
- opcua-jsonは各値を{ "value": v, "sourceTimestamp": null }としてラップ

ユースケース

シンプルなキーを期待するデータベースへの取り込みのためのSparkplug Bからフラット JSONへ
アラート前にノードメタデータを削除するためのOPC-UA JSONからフラット JSONへ
Sparkplug準拠のMQTTブローカーへのパブリッシュ時のフラット JSONからSparkplug Bへ
フラットキースペースを期待するダウンストリームコネクタのためのネストJSONのフラット化

例: OPC-UAからフラットJSONへ

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

入力:

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

出力:

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

例: フラットJSONからネストJSONへ

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

入力: { "temp": 25.5, "press": 101.3 }

出力: { "sensor": { "temperature": 25.5, "pressure": 101.3 } }

ベストプラクティス

keyMappingsを使用して、上流のタグ名をダウンストリームのスキーマ規約と1ステップで整合
キーリネームを超える値レベルの変更（数式、型変換）にはTransformと組み合わせる
Sparkplug Bペイロードはnameとvalueフィールドを持つオブジェクトのmetrics配列を含む必要があります — ソースが信頼できない場合は上流で検証
flat-json -> opcua-json -> flat-jsonのラウンドトリッピングはサポートされていますが、エンコード時にsourceTimestampはnullに設定されます