後端功能 #11528
由 Sam Wang 於 18 天 前更新
提供場景的建立、查詢、更新、刪除與執行功能。
| Method | Uri | 說明|
|:---| ---|:---|
|<code class="get">GET</code>|`/api/Scenes`|取得所有場景設定|
|<code class="get">GET</code>|`/api/Scenes/{id}`|取得特定場景設定|
|<code class="post">POST</code>|`/api/Scenes`|新增場景|
|<code class="put">PUT</code>|`/api/Scenes`|批量修改場景 (全覆蓋)|
|<code class="put">PUT</code>|`/api/Scenes/{id}`|修改特定場景設定|
|<code class="del">DELETE</code>|`/api/Scenes`|刪除所有場景|
|<code class="del">DELETE</code>|`/api/Scenes/{id}`|刪除特定場景|
### ◉ 場景參數說明
| 參數 | 類型 | 說明 |
| :--- | :--- | :--- |
| `name` | 字串 | 場景名稱 |
| `mode` | 整數 | **執行策略**<br>0: (預設) 若執行中再次觸發則忽略<br>1: 中斷並重新執行 (Restart)<br>2: 僅中斷目前執行 (Stop Only) |
| `actions` | 陣列 | **動作列表**。每個項目為物件：<br>- `id`: (字串) 指令，如 `MODBUS|1|light|ON`<br>- `delay`: (整數) 執行前延遲，單位為 **100ms** (5=0.5秒) |
### ◉ 控制場景 (API / MQTT) [POST]
場景（以及排程、智慧邏輯、設備）的觸發與控制皆透過統一的指令介面。
指令格式：`Sys|scenes|{scene_id}|{狀態}`
- **狀態 `1`**: 啟動場景
- **狀態 `0`**: 停止運行中的場景
- **狀態 `2`**: 切換場景 (Toggle)
**1. 透過 REST API 控制**
<code class="post">POST</code> <code class="posttxt">/api/Status</code></br>**發送統一控制命令 (可同時觸發多筆)**
```json
{
"actions": [
"Sys|scenes|{scene_id}}|1",
"Sys|scenes|{scene_id}|1"
]
}
```
**2. 透過 MQTT 控制**
發布 (Publish) 控制訊息至伺服器的命令 Topic (例如：`omni/{ServerID}`)：
```json
{
"cmd": "device.control",
"cid": "CID_123400",
"timestamp": 1773129540945,
"payload": {
"actions": [
"Sys|scenes|1|1"
]
}
}
```
### ◉ 取得所有場景 [GET]
<code class="get">GET</code> <code class="gettxt">/api/Scenes</code></br>**取得系統中所有場景設定**
|Response ✅ 成功 (200 OK)|
|---|
```json
{
"code": 0,
"message": "",
"timestamp": 1773129540945,
"payload": {
"ver": 1,
"1": {
"id": "1",
"name": "會議室燈光_ON",
"全關模式",
"mode": 1,
"actions": [
{
"id": "MODULE|1|point_01-1|0",
"MODBUS|1|light_01|OFF", "delay": 0
},
{
"id": "MODULE|1|point_01-2|0",
"MQTTIOT|sensor_01|switch|OFF", "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]
<code class="post">POST</code> <code class="posttxt">/api/Scenes</code></br>**手動新增一筆場景設定**
|Request|
|---|
```json
{
"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)|
|---|
```json
{
"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]
<code class="put">PUT</code> <code class="puttxt">/api/Scenes/{id}</code></br>**修改指定 ID 之場景內容**
|Request|
|---|
```json
{
"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)|
|---|
```json
{
"code": 0,
"message": "",
"timestamp": 1773127233478
}
```
### ◉ 刪除場景 [DELETE]
<code class="del">DELETE</code> <code class="deltxt">/api/Scenes/{id}</code></br>**刪除指定 ID 之場景**
|Response ✅ 成功 (200 OK)|
|---|
```json
{
"code": 0,
"message": "",
"timestamp": 1773127011473,
"payload": null
}
```