數據查詢 API
查詢分析結果與統計數據。
📐 數據模型說明： Kafka
scene-analysis-results訊息同時攜帶current+rolling5Min+rolling30Min+total數據。Core API Consumer 收到後拆分寫入兩張表：
current→scene_analytics_snapshots表（Snapshots API 查詢）rolling5Min/rolling30Min/total→scene_analytics_rolling表（Rolling API 查詢）
端點概覽
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/analytics/snapshots | 查詢快照歷史 |
| GET | /api/v1/analytics/snapshots/latest | 取得最新快照 |
| GET | /api/v1/analytics/rolling | 查詢滾動統計歷史 |
| GET | /api/v1/analytics/rolling/latest | 取得各視窗最新滾動統計 |
| GET | /api/v1/analytics/scenes/{id}/latest | 取得場景綜合最新指標 |
💡 Insights 與 Attributes API 已移至 Insights API (VLM) 頁面。
使用場景
- 歷史查詢：查詢特定時間範圍的快照記錄
- 趨勢分析：使用滾動統計觀察趨勢（5 / 30 分鐘等視窗）
- 即時監控：取得最新快照與滾動統計
- 報表產出：取得場景綜合指標進行分析
查詢快照歷史
GET /api/v1/analytics/snapshots
Query 參數
| 參數 | 型別 | 必填 | 範圍/限制 | 預設 | 說明 |
|---|---|---|---|---|---|
sceneId | String (UUID) | ✅ | - | - | 場景 ID |
startDate | String (ISO 8601) | ❌ | - | - | 開始時間 |
endDate | String (ISO 8601) | ❌ | - | - | 結束時間 |
page | Number | ❌ | 1-∞ | 1 | 頁碼 |
limit | Number | ❌ | 1-100 | 20 | 每頁數量 |
響應範例
{
"success": true,
"statusCode": 200,
"data": [
{
"id": "snapshot-uuid",
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"sceneType": "queue_analysis",
"windowStart": "2026-01-29T10:00:00Z",
"windowEnd": "2026-01-29T10:00:00Z",
"durationSeconds": 0,
"currentMetrics": {
"inQueue": 8,
"inService": 2
},
"computeNodeId": "compute-node-uuid",
"createdAt": "2026-01-29T10:00:00Z"
}
],
"meta": {
"pagination": { "page": 1, "limit": 20, "total": 480, "totalPages": 24 }
}
}
取得最新快照
GET /api/v1/analytics/snapshots/latest
取得場景最近 N 筆快照。
Query 參數
| 參數 | 型別 | 必填 | 範圍/限制 | 預設 | 說明 |
|---|---|---|---|---|---|
sceneId | String (UUID) | ✅ | - | - | 場景 ID |
limit | Number | ❌ | 1-100 | 10 | 回傳筆數 |
查詢滾動統計歷史
GET /api/v1/analytics/rolling
Query 參數
| 參數 | 型別 | 必填 | 範圍/限制 | 預設 | 說明 |
|---|---|---|---|---|---|
sceneId | String (UUID) | ✅ | - | - | 場景 ID |
windowType | String (enum) | ❌ | 5min / 15min / 30min / 60min / total | - | 視窗類型 |
startDate | String (ISO 8601) | ❌ | - | - | 開始時間 |
endDate | String (ISO 8601) | ❌ | - | - | 結束時間 |
page | Number | ❌ | 1-∞ | 1 | 頁碼 |
limit | Number | ❌ | 1-100 | 20 | 每頁數量 |
取得最新滾動統計
GET /api/v1/analytics/rolling/latest
取得各視窗類型的最新一筆滾動統計。
Query 參數
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
sceneId | String (UUID) | ✅ | 場景 ID |
響應範例
{
"success": true,
"data": {
"5min": { "...完成/放棄統計..." },
"15min": { "...完成/放棄統計..." },
"30min": { "...完成/放棄統計..." },
"60min": { "...完成/放棄統計..." },
"total": { "...完成/放棄統計..." }
}
}
取得場景綜合最新指標
GET /api/v1/analytics/scenes/{id}/latest
取得場景的完整最新指標，包含快照和滾動統計。
Query 參數
| 參數 | 型別 | 必填 | 預設 | 說明 |
|---|---|---|---|---|
includeSnapshots | Boolean | ❌ | true | 是否包含快照 |
includeRolling | Boolean | ❌ | true | 是否包含滾動統計 |
snapshotLimit | Number | ❌ | 10 | 快照數量限制 |
響應範例
{
"success": true,
"data": {
"sceneId": "scene-uuid",
"snapshots": [
{
"id": "snapshot-uuid",
"currentMetrics": { "inQueue": 8, "inService": 2 },
"createdAt": "2026-01-29T10:00:00Z"
}
],
"rolling": {
"5min": { "..." },
"15min": { "..." },
"30min": { "..." },
"60min": { "..." },
"total": { "..." }
},
"lastUpdatedAt": "2026-01-29T10:00:05Z"
}
}
Analysis Insights & Attributes
Insights 與 Attributes 相關 API 已移至獨立頁面：
- Insights API (VLM) — 洞察列表、詳情、VLM 摘要、屬性關聯查詢
- AI Search API (LLM) — LLM 自然語言搜尋