# 影像監控系統
:::success
本應用實務依據``5G智慧杆技術規範``，詳細定義了資料交換格式、欄位定義、API 操作規則及錯誤處理機制，旨在確保各縣市政府與系統整合商能順利實施智慧杆影像監控數據的採集、分析與共享，達到系統間無縫互通。特別針對主流 AI 辨識引擎功能特性，提供數據交換框架，提升智慧城市各監控系統彼此間的相容性。
:::
[toc]
## 欄位與資料定義
本節詳細定義智慧杆影像監控系統數據交換所需的各項欄位，包括基本資訊、分析結果及配置參數等。
* **JSON 資料結構整合範例**
```json
{
"deviceId": "uuid-xxx-yyy-zzz",
"DEVSNo": "STC-2025A-0012",
"poleId": "TP-NC-001",
"timestamp": "2025-05-01T10:00:00.000Z",
"status": 1,
"surveillance": {
"station": "智慧杆第五分站",
"jurisdiction": "臺北市大安區",
"datetype": "STREAM",
"resolution": 1080,
"bandwidth": 4096
},
"aiAnalysis": {
"eventId": "e12a45b7-89cd-4ef0-ab12-456789abcdef",
"eventType": "person_detected",
"eventStartTime": "2025-05-01T10:00:05.000Z",
"objectType": "person",
"objectId": "obj-123456",
"objectCount": 1,
"boundingBox": [120, 140, 80, 190],
"confidenceScore": 0.97,
"behaviorType": "walking",
"thumbnailUrl": "https://storage.example.com/events/e12a45b7/thumbnail.jpg"
}
}
```
### 基本資訊欄位
| 欄位名稱 | 格式 | 必填 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | API 請求驗證令牌 | 需包含在 HTTP Request Header |
| DEVSNo | String | M | 攝影機編號 | 同一智慧杆上可有多個攝影機 |
| timestamp | DateTime | M | 數據產生時間 | ISO8601 格式(YYYY-MM-DDThh:mm:ss.sssZ) |
| **surveillance** | Object | M | 影像監控系統封裝物件 | 詳見 surveillance 物件欄位說明 |
| **aiAnalysis** | Object | O | AI 辨識分析資料 | 詳見 aiAnalysis 物件欄位說明 |
| firmwareVersion | String | O | 設備韌體版本 | 用於相容性判斷 |
| status | Integer | M | 設備運行狀態 | 0:離線, 1:正常, 2:警告, 3:錯誤 |
### surveillance 物件欄位
| 欄位名稱 | 格式 | 必填 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| station | String | M | 監控站點名稱或編號 | 監控節點識別 |
| jurisdiction | String | M | 管理單位內部系統指定之管轄區域劃分 | 例: 警勤區、工業區名稱、河川流域名稱 |
| zip | String | O | 攝影機設置地址郵遞區號 | 方便管理 |
| address | String | O | 攝影機設置地址 | 方便管理 |
| keyword | String | O | 關鍵字 | 便於資訊索引 |
| datatype | Array | M | 影像資料形式 | Enum：NONE、MESSAGE、PICTURE、VIDEO、STREAM、OTHER |
| resolution | 數字 | O | 解析度 | 例: 480, 1080, 2160 |
| bandwidth | 數字 | O | 預估所需頻寬(kbps) | 用於網路資源規劃 |
### aiAnalysis 物件欄位
| 欄位名稱 | 格式 | 必填 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| eventId | String | M | 事件唯一識別碼（UUID） | 用於事件追蹤與關聯管理 |
| eventType | String | M | 事件類型 | 參照事件類型代碼表 |
| eventStartTime | DateTime | M | 事件開始時間 | ISO8601 格式 |
| eventEndTime | DateTime | O | 事件結束時間 |持續事件需填寫 |
| objectType | String | M | 被偵測物體類型 | 例: person、vehicle |
| objectId | String | O | 物體唯一識別碼 | 支援跨鏡頭追蹤 |
| objectCount | Integer | O | 物體數量 | 計數事件必填 |
| boundingBox | Array[Int] | O | 偵測物邊界框 [x, y, width, height] | 影像坐標系 |
| confidenceScore | Float (0~1) | M | AI 辨識可信度 | 越高代表辨識結果越可靠 |
| behaviorType | String | O | 行為類型 | 例: fall、fight、tailgating |
| dwellTime | Integer | O | 停留時間（秒） | 停留事件必填 |
| direction | Integer | O | 移動方向（0~359度） | 角度制 |
| speed | Float | O | 移動速度（m/s） | 根據場地大小換算 |
| skeletonPoints | Array | O | 骨架追蹤點坐標陣列 | 用於人體姿態分析 |
| reIdFeature | String | O | 再識別特徵向量（Base64編碼） | 跨鏡頭身份追蹤 |
| attributes | Object | O | 目標物附加屬性 | 例: 性別、年齡段、服裝顏色等 |
| relatedEvents | Array[String] | O | 相關聯事件 ID | 用於事件關聯與串接 |
| thumbnailUrl | String | O | 事件縮圖 URL | 用於前端快速展示影像 |
| logicalRuleId | String | O | 觸發的邏輯規則 ID | 複雜事件判斷依據 |
* **aiAnalysis 物件 JSON 範例**
```json
"aiAnalysis": {
"eventId": "e12a45b7-89cd-4ef0-ab12-456789abcdef",
"eventType": "person_detected",
"eventStartTime": "2025-05-01T10:00:05.000Z",
"eventEndTime": null,
"objectType": "person",
"objectId": "obj-123456",
"objectCount": 1,
"boundingBox": [120, 140, 80, 190],
"confidenceScore": 0.97,
"behaviorType": "walking",
"dwellTime": 15,
"direction": 45,
"speed": 1.2,
"skeletonPoints": [
[125, 145],
[130, 160],
[140, 190]
],
"reIdFeature": "Q29tcHV0ZXJTY2VuZQ==",
"attributes": {
"gender": "male",
"ageGroup": "adult",
"clothing": {
"upperColor": "#2233CC",
"lowerColor": "#222222"
}
},
"relatedEvents": ["evt-20250430-001", "evt-20250430-002"],
"thumbnailUrl": "https://storage.example.com/events/e12a45b7/thumbnail.jpg",
"logicalRuleId": "rule-2025-03-01"
}
```
## 資料結構與操作規則
本節定義智慧杆影像監控系統數據的資料結構和相關操作規則，以確保數據交換的一致性和可靠性。
### 資料模型與關聯
智慧杆影像監控系統的數據模型主要包含以下幾個實體及其關聯：
* 設備（Device）：代表智慧杆上的實體設備，包括攝影機和相關感測器
* 事件（Event）：由 AI 引擎分析產生的各類事件
* 物體（Object）：被偵測到的人、車輛或其他物體
* 配置（Configuration）：系統配置參數，如偵測區域、計數線等
這些實體之間的關聯如下：
* 一支智慧杆可包含多個設備
* 一個設備可產生多個事件
* 一個事件可涉及多個物體
* 一個設備可有多個配置
### API 操作規則
* **新增操作:**
用於新增事件數據或設備註冊
```
POST /api/v1/events
```
請求參數：
包含事件基本資訊和分析結果的 JSON 物件
回應狀態碼：
- 201：創建成功
- 400：請求格式錯誤
- 401：未授權
- 500：伺服器錯誤
回應格式：
```
{
"status": "success",
"code": 201,
"message": "事件已創建",
"data": {
"eventId": "e12a45b7-89cd-4ef0-ab12-456789abcdef"
}
}
```
* **查詢操作:**
用於查詢事件數據或設備狀態
```
GET /api/v1/events
```
請求參數：
* deviceId (選填)：設備ID
* poleId (選填)：智慧杆ID
* eventType (選填)：事件類型
* startTime (選填)：查詢開始時間
* endTime (選填)：查詢結束時間
* page (選填)：頁碼，預設值 1
* pageSize (選填)：每頁記錄數，預設值 20
* sort (選填)：排序欄位，預設 timestamp
* order (選填)：排序方式，asc 或 desc，預設 desc
回應狀態碼：
- 200：查詢成功
- 400：參數錯誤
- 401：未授權
- 404：無資料
- 500：伺服器錯誤
回應格式：
```
{
"status": "success",
"code": 200,
"message": "查詢成功",
"data": {
"total": 128,
"page": 1,
"pageSize": 20,
"events": [
{
"eventId": "e12a45b7-89cd-4ef0-ab12-456789abcdef",
"deviceId": "d1e23f45-67g8-9h0i-jk12-lmnopqrstuvw",
"eventType": "person_detected",
"timestamp": "2025-04-30T08:15:30.123Z",
"...": "其他欄位"
},
"...其他事件"
]
}
}
```
* **修改操作:**
用於更新事件數據或設備配置
```
PUT /api/v1/events/{eventId}
```
請求參數：
* eventId：事件ID
* 需要更新的欄位及值
回應狀態碼：
* 200：更新成功
* 400：請求格式錯誤
* 401：未授權
* 404：資源不存在
* 500：伺服器錯誤
回應格式：
```
{
"status": "success",
"code": 200,
"message": "事件已更新",
"data": {
"eventId": "e12a45b7-89cd-4ef0-ab12-456789abcdef",
"updatedAt": "2025-04-30T08:20:30.123Z"
}
}
```
* **刪除操作:**
用於刪除事件數據或設備註冊
```
DELETE /api/v1/events/{eventId}
```
請求參數：
* eventId：事件ID
回應狀態碼：
* 204：刪除成功
* 400：請求格式錯誤
* 401：未授權
* 404：資源不存在
* 500：伺服器錯誤
回應格式：
```
{
"status": "success",
"code": 204,
"message": "事件已刪除"
}
```
### 使用限制與交換頻率
為確保系統穩定性與資源合理利用，API 的使用應遵循以下限制：
1. 事件數據實時交換：
* 緊急事件（例: 跌倒、打鬥）：實時上傳，最大延遲不超過1秒
* 一般事件：批次上傳，頻率不超過每10秒一次
* 統計數據：批次上傳，頻率不超過每分鐘一次
2. API 請求限制：
* 每個 API 端點的請求頻率限制為每分鐘300次
* 每個 IP 地址的請求頻率限制為每分鐘500次
* 查詢操作單次返回記錄數上限為1000條
3. 資料保留政策：
* 事件數據保留期限為90天
* 統計數據保留期限為365天
## 錯誤處理規則
所有 API 回應都應遵循統一的錯誤處理格式，確保系統各組件能一致解析錯誤資訊。
標準錯誤回應格式：
```
{
"status": "error",
"code": 400,
"message": "錯誤描述",
"errors": [
{
"field": "欄位名稱",
"code": "錯誤代碼",
"message": "詳細錯誤說明"
}
]
}
```
### 常見錯誤代碼及處理方式
| 錯誤代碼 | 說明 | 處理建議 |
| -------- | -------- | -------- |
| 400 | 請求格式錯誤 | 檢查請求參數格式和內容 |
| 401 | 未授權訪問 | 檢查認證憑證是否有效 |
| 403 | 無權限操作 | 申請必要的操作權限 |
| 404 | 資源不存在 | 確認所請求資源的識別碼是否正確 |
| 409 | 資源衝突 | 解決資源衝突後重試 |
| 429 | 請求過於頻繁 | 降低請求頻率，遵守使用限制。 |
| 500 | 伺服器內部錯誤 | 聯繫系統管理員解決 |
| 503 | 服務暫時不可用 | 稍後重試或聯繫系統管理員 |
## 資料格式與代碼支援
本節提供資料交換所需的 JSON 格式規範、範例代碼和代碼表。
### JSON 格式規範
所有資料交換必須使用 JSON 格式，並符合以下規範：
- 字符編碼：UTF-8
- 日期時間格式：ISO8601 (YYYY-MM-DDThh:mm:ss.sssZ)
- 數值精度：浮點數精確到小數點後3位
- 地理座標：採用 WGS84 座標系統
- 數組和對象表示：遵循標準 JSON 格式
- 空值處理：必填欄位不得為 null，選填欄位可為 null
### 代碼表
| 代碼 | 說明 |
| -------- | -------- |
| **事件類型代碼** | |
| person_detected | 人員偵測 |
| vehicle_detected | 車輛偵測 |
| animal_detected | 動物偵測 |
| object_abandoned | 棄置物 |
| counting | 計數事件 |
| direction_analysis | 方向分析 |
| dwell | 停留 |
| tailgating | 尾隨 |
| tamper | 設備干擾 |
| fall | 跌倒 |
| fight | 打鬥 |
| interaction | 人物互動 |
| line_crossing | 越線 |
| zone_entering | 進入區域 |
| zone_exiting | 離開區域 |
| behavior_analysis | 行為分析 |
| object_tracking | 物體追蹤 |
| system_alert | 系統警報 |
| **物體類型代碼表** | |
| person | 人員 |
| car | 小型車輛 |
| truck | 大型車輛 |
| motorcycle | 機車 |
| bicycle | 自行車 |
| animal | 動物 |
| package | 包裹 |
| bag | 袋子 |
| unknown | 未知物體 |
| **行為類型代碼表** | |
| walking | 行走 |
| running | 奔跑 |
| standing | 站立 |
| sitting | 坐著 |
| falling | 跌倒 |
| fighting | 打鬥 |
| gathering | 聚集 |
| lingering | 徘徊 |
| erratic | 不規則移動 |
| abandoning | 拋棄物品 |
| taking | 拿取物品 |
| exchanging | 物品交換 |
| loitering | 閒蕩 |
Sign in with Wallet
Connect another wallet