動作
後端功能 #11528
進行中
後端功能 #11091: Omni IoT Server
場景管理 (Scenes)
概述
提供場景的建立、查詢、更新、刪除與執行功能。
| Method | Uri | 說明 |
|---|---|---|
GET |
/api/Scenes |
取得所有場景設定 |
GET |
/api/Scenes/{id} |
取得特定場景設定 |
POST |
/api/Scenes |
新增場景 |
PUT |
/api/Scenes |
批量修改場景 (全覆蓋) |
PUT |
/api/Scenes/{id} |
修改特定場景設定 |
DELETE |
/api/Scenes |
刪除所有場景 |
DELETE |
/api/Scenes/{id} |
刪除特定場景 |
◉ 場景參數說明¶
| 參數 | 類型 | 說明 |
|---|---|---|
name |
字串 | 場景名稱 |
mode |
整數 |
執行策略 0: (預設) 若執行中再次觸發則忽略 1: 中斷並重新執行 (Restart) 2: 僅中斷目前執行 (Stop Only) |
actions |
陣列 |
動作列表。每個項目為物件： - id: (字串) 指令，如 `MODBUS |
◉ 控制場景 (API / MQTT) [POST]¶
場景（以及排程、智慧邏輯、設備）的觸發與控制皆透過統一的指令介面。
指令格式：Sys|scenes|{scene_id}|{狀態}
-
狀態
1: 啟動場景 -
狀態
0: 停止運行中的場景 -
狀態
2: 切換場景 (Toggle)
1. 透過 REST API 控制
POST /api/Status發送統一控制命令 (可同時觸發多筆)
{
"actions": [
"Sys|scenes|{scene_id}}|1",
"Sys|scenes|{scene_id}|1"
]
}
2. 透過 MQTT 控制
發布 (Publish) 控制訊息至伺服器的命令 Topic (例如：omni/{ServerID})：
{
"cmd": "device.control",
"cid": "CID_123400",
"timestamp": 1773129540945,
"payload": {
"actions": [
"Sys|scenes|1|1"
]
}
}
◉ 取得所有場景 [GET]¶
GET /api/Scenes取得系統中所有場景設定
| Response ✅ 成功 (200 OK) |
|---|
{
"payload": {
"1": {
"id": "1",
"name": "會議室燈光_ON",
"mode": 1,
"actions": [
{
"id": "MODULE|1|point_01-1|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-2|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-3|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-4|0",
"delay": 0
},
{
"id": "MODULE|1|point_02-1|0",
"delay": 0
},
{
"id": "MODULE|1|point_02-2|0",
"delay": 0
},
{
"id": "MODULE|1|point_02-3|0",
"delay": 0
},
{
"id": "MODULE|1|point_02-4|0",
"delay": 0
}
]
},
"ver": 2
},
"code": 0,
"message": "",
"timestamp": 1773127011473
}
◉ 新增場景 [POST]¶
POST /api/Scenes手動新增一筆場景設定
| Request |
|---|
{
"name": "會議室燈光_OFF",
"mode": 1,
"actions": [
{
"id": "MODULE|1|point_01-1|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-2|0",
"delay": 0
}
]
}
| Response ✅ 成功 (201 Created) |
|---|
{
"code": 0,
"message": "",
"timestamp": 1773127011473,
"payload": {
"id": "2",
"name": "會議室燈光_OFF",
"mode": 1,
"actions": [
{
"id": "MODULE|1|point_01-1|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-2|0",
"delay": 0
}
]
}
}
◉ 修改場景 [PUT]¶
PUT /api/Scenes/{id}修改指定 ID 之場景內容
| Request |
|---|
{
"name": "會議室燈光_OFF",
"mode": 1,
"actions": [
{
"id": "MODULE|1|point_01-1|0",
"delay": 0
},
{
"id": "MODULE|1|point_01-2|0",
"delay": 0
}
]
}
| Response ✅ 成功 (200 OK) |
|---|
{
"code": 0,
"message": "",
"timestamp": 1773127233478
}
◉ 刪除場景 [DELETE]¶
DELETE /api/Scenes/{id}刪除指定 ID 之場景
| Response ✅ 成功 (200 OK) |
|---|
{
"code": 0,
"message": "",
"timestamp": 1773127011473,
"payload": null
}
動作