MQTT 配信・購読スクリプトマニュアル

スクリプトの構文は Lua です。接続・配信・購読設定の全体概念は MQTT クラウド・エッジ連携 を先に参照してください。このページでは配信・購読スクリプトの書き込みパラメーター、完全なスクリプト例、要求・応答メッセージ形式を説明します。

概要

1. MQTT データの配信形式を定義し、CRON タスクでアップロードできます。
2. 購読メッセージの解析を定義し、Edge-EMS Builder バックエンドが解析結果に従って指定ポイントへ書き込みます。
3. 購読メッセージ処理後の response の要否、topic、内容を定義できます。

注：プログラミングの基礎と MQTT のパブリッシュ／サブスクライブの流れに関する知識が必要です。構文は Lua スクリプト完全リファレンス を参照してください。

参照ポイントの値を取得できない場合、センチネル文字列 __Null__ が挿入されます。空文字列や nil と仮定せず、${dataKey} == "__Null__" で明示的に判定してください。

MQTT 接続

パラメーター名	値	必須	型	説明
mqttConnectionConfigName	接続設定名	はい	String	MQTT 接続設定の名前
status	Valid	はい	String	状態（接続を有効にするか）
protocol	mqtts	はい	String	MQTT プロトコル（mqtt/mqtts に対応）
protocolVersion	3.1.1	はい	String	MQTT バージョン（3.1/3.1.1/5.0 に対応）
serverHost	127.0.0.1	はい	String	MQTT 接続先アドレス
serverPort	8883	はい	String	MQTT 接続ポート
clientId	return "demo-edge"	はい	String	クライアント ID を返す Lua 式
username	username	はい	String	ユーザー名
password	password	はい	String	パスワード
cleanSession	true	はい	Boolean	セッションのクリーンアップ
sessionExpiryInterval	0	はい	Number	セッション有効期限間隔（MQTT5.0 固有）
keepAliveInterval	60	はい	String	ハートビート間隔
connectTimeout	30	はい	String	接続タイムアウト
sslEnable	true	はい	Boolean	SSL を使用するか

MQTT データ配信

パラメーター名	値	必須	型	説明
mqttConnectionConfigId	100101	はい	Number	MQTT 接続設定 ID
mqttPublishConfigName	配信設定名	はい	String	MQTT 配信設定の名前
topic	return "demo/telemetry"	はい	String	Topic を返す Lua 式
qos	“1”	はい	String	QoS の文字列列挙値
publishStrategy	0/10 * * * * ?	はい	String	配信スケジュール（CRON 式）
publishContent	{“name”: “dataKey”}	はい	String	配信内容（Lua スクリプト）
note	note	はい	String	備考

配信経路はスクリプト結果を JSON へシリアライズします。オブジェクトを配信する場合は Lua table を直接返してください。先に toJsonString を呼ぶと、引用符付きの JSON 文字列になります。

publishContent 例 1（Table の構築）

local map = {}
-- 時刻
map.time = OffsetDateTime.now():unixMilli()
-- 通常のデータ値
map.name = "${数据8}"
-- 文字列配列
map.strList = { "${数据3}", "${数据4}" }
-- 数値配列
local d3 = ${数据3}
local d4 = ${数据4}
map.numberList = { d3, d4 }

return map

publishContent 例 2（文字列の連結）

local json = '{"strList":["${数据3}","${数据4}"],"name":"${数据8}","time":' .. OffsetDateTime.now():unixMilli() .. ',"numberList":[' .. ${数据3} .. ',' .. ${数据4} .. ']}'
return jsonToMap(json)

解析結果

{
    "strList": [
        "3.6",
        "0.6"
    ],
    "name": "2",
    "time": 1742180870064,
    "numberList": [
        3.6,
        0.6
    ]
}

MQTT メッセージ購読

パラメーター名	値	必須	型	説明
mqttConnectionConfigId	2	はい	Number	MQTT 接続設定 ID
mqttSubscribeConfigName	購読設定名	はい	String	MQTT 購読設定の名前
status	Valid	はい	String	状態
topic	return "demo/commands"	はい	String	Topic を返す Lua 式
qos	“1”	はい	String	QoS の文字列列挙値
actionContent	{}	はい	String	アクション内容（Lua スクリプト）
needResponse	true	はい	Boolean	response が必要か
responseTopic	return "demo/replies"	応答有効時	String	応答 Topic を返す Lua 式
response	return {ok=true}	応答有効時	String	応答スクリプト。文字列はそのまま送信し、table は JSON へシリアライズ
note	note	はい	String	備考

actionContent：購読 message の解析

書き込みパラメーター

パラメーター名	値	必須	型	説明
dataType	Customization	はい	String	操作するデータ型：Customization/Collection/Aggregation
dataKey	功率	はい	String	データの一意の dataKey
dataValue	topic	はい	String	データ値
availableDate	2023-01-15T07:00:00+08:00	いいえ	String	有効開始日時（Customization）
expiredDate	2023-01-15T10:00:00+08:00	いいえ	String	有効終了日時（Customization）

固定パラメーター：

${subscribe_message}：topic から受信した message。

Edge-EMS Builder の dataKey は、上記の固定 dataKey と重複しないように設定してください。

actionContent の解析

local messageMap = jsonToMap(${subscribe_message})
local params = messageMap.params
local strategyList = jsonToListMap(toJsonString(params.strategy))
local date = params.date
local resultList = {}

for i, keyMap in ipairs(strategyList) do
    local availableDate = completeDateTime(date .. "T" .. keyMap.start)
    local expiredDate = completeDateTime(date .. "T" .. keyMap["end"])

    -- 書き込むデータ型：Collection（生データ）/Customization（時間帯別データ）/Aggregation（集約データ）
    local modeMap = buildCommonWriteMap("Customization", "mode", tostring(keyMap.mode), availableDate, expiredDate, false)
    local chargeMap = buildCommonWriteMap("Customization", "charge", tostring(keyMap.charge), availableDate, expiredDate, false)
    local valueMap = buildCommonWriteMap("Customization", "value", tostring(keyMap.value), availableDate, expiredDate, false)

    table.insert(resultList, modeMap)
    table.insert(resultList, chargeMap)
    table.insert(resultList, valueMap)
end

table.insert(resultList, buildSlaveWriteMap("DeviceB", "Share", "数据4", 777, nil, nil, false))

return resultList

要求例

/rpc/${iot_code}/${method}/request

購読 Topic：/rpc/yanhua001/ems/strategy/request

注：iot_code は集約データです。

送信メッセージ

{
  "jsonrpc":"2.0",
   "id":"d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9",
   "method":"ems/strategy",
   "params":{
    "date":"2023-1-15",
    "strategy":[
     {
      "strategyDate":"2023-1-15",
      "start":"00:00:00",
      "end":"05:00:00",
      "mode":1,
      "charge":true,
      "value":100
      },
     {
      "start":"05:00:00",
      "end":"07:00:00",
      "mode":2,
      "charge":false,
      "value":100
     }
    ]
  }
 }

action の解析結果

解析結果の要件：

1. dataType は Collection（生データ）、Customization（時間帯別データ）、Aggregation（集約データ）のいずれかです。
2. dataKey が存在する必要があります。
3. 同じ Customization の dataKey に複数の value がある場合、各 value の有効期間を重複させてはいけません。
4. Customization 更新時は、既存データをすべて削除し、今回配信されたデータへ置き換えます。

{
    "actionType": "SUBSCRIBE",
    "actionResult": true,
    "mqttActionContent": {
        "Customization": {
            "mode": [
                {
                    "dataType": "Customization",
                    "dataKey": "mode",
                    "dataValue": "1",
                    "availableDate": "2023-01-15T00:00:00+08:00",
                    "expiredDate": "2023-01-15T05:00:00+08:00"
                },
                {
                    "dataType": "Customization",
                    "dataKey": "mode",
                    "dataValue": "2",
                    "availableDate": "2023-01-15T05:00:00+08:00",
                    "expiredDate": "2023-01-15T07:00:00+08:00"
                }
            ],
            "charge": [
                {
                    "dataType": "Customization",
                    "dataKey": "charge",
                    "dataValue": "true",
                    "availableDate": "2023-01-15T00:00:00+08:00",
                    "expiredDate": "2023-01-15T05:00:00+08:00"
                },
                {
                    "dataType": "Customization",
                    "dataKey": "charge",
                    "dataValue": "false",
                    "availableDate": "2023-01-15T05:00:00+08:00",
                    "expiredDate": "2023-01-15T07:00:00+08:00"
                }
            ],
            "value": [
                {
                    "dataType": "Customization",
                    "dataKey": "value",
                    "dataValue": "100",
                    "availableDate": "2023-01-15T00:00:00+08:00",
                    "expiredDate": "2023-01-15T05:00:00+08:00"
                },
                {
                    "dataType": "Customization",
                    "dataKey": "value",
                    "dataValue": "100",
                    "availableDate": "2023-01-15T05:00:00+08:00",
                    "expiredDate": "2023-01-15T07:00:00+08:00"
                }
            ]
        }
    },
    "mqttActionResult": {

    }
}

responseTopic：response の購読先を解析

固定パラメーター：

${subscribe_message}：topic から受信した message。

${subscribe_result}：actionContent の実行が成功したか。

${subscribe_result_message}：actionContent の実行結果。action の解析結果 を参照。

Edge-EMS Builder の dataKey は、上記の固定 dataKey と重複しないように設定してください。

responseTopic の解析

local messageMap = jsonToMap(${subscribe_message})
local id = messageMap.id
local method = messageMap.method
return "/rpc/" .. "${iot_code}" .. "/" .. method .. "/response/" .. id

要求例

/rpc/${iot_code}/${method}/response/${id}

応答先 topic：/rpc/yanhua001/ems/strategy/response/d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9

送信メッセージ

{
  "jsonrpc":"2.0",
   "id":"d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9",
   "method":"ems/strategy",
   "params":{
    "date":"2023-1-15",
    "strategy":[
     {
      "strategyDate":"2023-1-15",
      "start":"00:00:00",
      "end":"05:00:00",
      "mode":1,
      "charge":true,
      "value":100
      },
     {
      "start":"05:00:00",
      "end":"07:00:00",
      "mode":2,
      "charge":false,
      "value":100
     }
    ]
  }
 }

topic の解析結果

/rpc/yanhua001/ems/strategy/response/d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9

response：返却する応答の組立て

response の解析

local messageMap = jsonToMap(${subscribe_message})
local id = messageMap.id
local jsonrpc = messageMap.jsonrpc
local result = "${subscribe_result}"

local resultMap = {}
resultMap.jsonrpc = jsonrpc
resultMap.result = result
resultMap.id = id

return resultMap

要求例

/rpc/${iot_code}/${method}/response/${id}

応答先 topic：/rpc/yanhua001/ems/strategy/response/d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9

送信メッセージ

{
  "jsonrpc":"2.0",
   "id":"d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9",
   "method":"ems/strategy",
   "params":{
    "date":"2023-1-15",
    "strategy":[
     {
      "strategyDate":"2023-1-15",
      "start":"00:00:00",
      "end":"05:00:00",
      "mode":1,
      "charge":true,
      "value":100
      },
     {
      "start":"05:00:00",
      "end":"07:00:00",
      "mode":2,
      "charge":false,
      "value":100
     }
    ]
  }
 }

topic の解析結果

注：実際には圧縮された JSON です。

{
    "result": "true",
    "id": "d1acc980-0e4e-11e8-98f0-ab5030b47df4:d1db7aa0-0e4e-11e8-b1d9-5f0ab230c0d9",
    "jsonrpc": "2.0"
}

次のステップ

• 接続・配信・購読設定と通信復旧後の再送：MQTT クラウド・エッジ連携
• Lua 組み込み関数とモジュールの完全リファレンス：Lua スクリプト完全リファレンス