分析控制 API
控制設備的分析啟動與停止。
端點概覽
| 方法 | 路徑 | 說明 |
|---|
| POST | /api/v1/devices/{id}/analysis/start | 啟動分析 |
| POST | /api/v1/devices/{id}/analysis/stop | 停止分析 |
| GET | /api/v1/devices/{id}/analysis/status | 取得分析狀態 |
使用場景
- 手動控制：即時啟動/停止特定場景的分析
- API 整合：由外部系統觸發分析
- 狀態查詢：確認當前分析是否運行中
💡 若已設定設備排程，系統會自動啟停分析，可跳過此步驟。
啟動分析
POST /api/v1/devices/{deviceId}/analysis/start
請求參數
| 參數 | 型別 | 必填 | 範圍/限制 | 說明 |
|---|
sceneId | String (UUID) | ✅ | - | 要執行的場景 ID |
priority | Number | ❌ | 1-5 | 優先級（1=最高），預設 3 |
前置條件
- 設備在線（
onlineStatus = online）
- 場景狀態為
active
- 設備配額未超限
- 分析未在運行中
響應 (202 Accepted)
{
"success": true,
"statusCode": 202,
"message": "Analysis started successfully",
"data": {
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"analysisId": "analysis-uuid",
"sceneType": "queue_analysis",
"status": "initializing",
"estimatedInitMs": 3000,
"createdAt": "2026-01-29T10:00:00Z"
},
"meta": {
"timestamp": "2026-01-29T10:00:00.000Z",
"requestId": "req-uuid",
"computeNodeId": "node-uuid"
}
}
錯誤碼
| 錯誤碼 | 說明 |
|---|
ALREADY_RUNNING | 分析已在運行中 |
DEVICE_OFFLINE | 設備離線 |
NO_ACTIVE_SCENES | 無可用場景 |
QUOTA_EXCEEDED | 配額已用罄 |
停止分析
POST /api/v1/devices/{deviceId}/analysis/stop
請求參數
| 參數 | 型別 | 必填 | 說明 |
|---|
reason | String (enum) | ❌ | 停止原因，預設 user_request |
drain | Boolean | ❌ | 是否等待緩衝區處理完畢，預設 false |
停止原因
| 值 | 說明 |
|---|
user_request | 用戶請求停止 |
timeout | 超時 |
error | 錯誤 |
resource_constraint | 資源限制 |
scheduled | 排程停止 |
響應 (200)
{
"success": true,
"statusCode": 200,
"message": "Analysis stopped successfully",
"data": {
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"analysisId": "analysis-uuid",
"sceneType": "queue_analysis",
"status": "stopped",
"stoppedAt": "2026-01-29T12:00:00Z",
"processingDuration": {
"seconds": 7200,
"milliseconds": 7200000
}
},
"meta": {
"timestamp": "2026-01-29T12:00:00.000Z",
"requestId": "req-uuid",
"computeNodeId": "node-uuid"
}
}
取得分析狀態
GET /api/v1/devices/{deviceId}/analysis/status
響應 (200)
{
"success": true,
"statusCode": 200,
"message": "Analysis status retrieved",
"data": {
"computeNodeHealth": "online",
"activeDeviceCount": 1,
"maxConcurrentDevices": 4,
"devices": [
{
"deviceId": "device-uuid",
"scenes": [
{
"sceneId": "scene-uuid",
"sceneType": "queue_analysis",
"status": "running",
"uptimeMs": 3600000,
"stats": {
"processedFrames": 5000,
"droppedFrames": 50,
"fps": 25.5,
"avgProcessingTimeMs": 120
},
"startedAt": "2026-01-29T10:00:00Z"
}
]
}
]
},
"meta": {
"timestamp": "2026-01-29T11:00:00.000Z",
"requestId": "req-uuid",
"computeNodeId": "node-uuid"
}
}
分析狀態
| 值 | 說明 |
|---|
initializing | 初始化中 |
running | 運行中 |
stopped | 已停止 |
error | 錯誤 |