這是本文件的舊版！
API 串接文件
文件概述
系統整合需求說明
客戶希望能夠讀取設備資料後，進行邊緣運算之後，提供結果給我方呈現在
EMS 畫面上
-
-
系統流程
整體串接流程圖
串接環境與部署資訊
API 端點資訊
API 功能總覽
| 動作 | 方法 | 路徑 | 說明 |
| 取得裝置列表 | GET | /devices | 使用複數命名，代表裝置資源集合 |
| 取得某裝置的資料 | GET | /devices/{deviceId} | 取得特定裝置（依據 deviceId）之詳細資料 |
| 新增計算後資料數據 | POST | /calculations | 將資料上傳至指定裝置，通常為裝置運算後需回傳的結果資料 |
讀取資料 API（GET）說明
請求標頭
查詢參數
| 欄位 | 格式 | 必填 | 說明 |
| deviceId | String | Required | 裝置唯一識別碼 |
| startTime | Datetime | Optional | 資料開始時間 (2025-04-18) |
| endTime | Datetime | Optional | 資料結束時間 (2025-05-18) |
回應參數
| 參數 | 型別 | 說明 |
| deviceId | String | 設備ID |
| deviceStatus | String | 設備狀態 (on/off) |
| timestamp | String | 時間 （ISO8601 格式） |
| rawData | Object | 實際設備數值 |
溫、濕度
| rawData 實際設備數值 |
| 參數 | 型別 | 說明 |
| temperature | Decimal | 溫度 |
| humidity | Decimal | 濕度 |
每小時瓩
| rawData 實際設備數值 |
| 參數 | 型別 | 說明 |
| kWh | Decimal | 每小時瓩 |
回應內容
[
{
"deviceId": "device-001",
"deviceStatus": "on",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"temperature": 26.4,
"humidity": 83.1
}
},
{
"deviceId": "device-002",
"deviceStatus": "off",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"kWh": 14257.231
}
}
]
上傳資料 API（POST）說明
請求標頭
上傳參數
| 參數 | 型別 | 說明 |
| deviceId | String | 裝置唯一識別碼 |
| clientId | String | 客戶 ID |
| timestamp | String (ISO8601) | 計算時間 |
| calculatedEnergy | Decimal | 計算電量 (時間區間內耗電kWh) |
| adjustedEnergy | Decimal | 調整後電量 (時間區間內耗電kWh) |
| calculatedSavingRate | Decimal | 計算節電率 0.00~1.00 |
| adjustedSavingRate | Decimal | 調整後節電率 0.00~1.00 |
| alertCode | String | 異常狀態碼（預設為 NO_ALERT） |
回應內容
{
"deviceId": "device-001",
"clientId": "client-001",
"timestamp": "2025-04-15T08:05:00Z",
"calculatedEnergy": 2.85,
"adjustedEnergy": 2.67,
"calculatedSavingRate": 0.17,
"adjustedSavingRate": 0.15,
"alertCode": "NO_ALERT"
}
異常狀態碼對照表（alertCode）
| 狀態碼 | 說明 |
| NO_ALERT | 無異常 |
| WARNING | 輕微異常，需注意 |
| CRITICAL | 嚴重異常，需處理 |
回應內容
錯誤代碼與說明（Error Codes）
| 錯誤代碼 | 錯誤訊息 |
| UNAUTHORIZED | API 金鑰無效或未授權 |
| SERVER_ERROR | 伺服器內部錯誤，請稍後再試 |
| INVALID_INPUT | 請求參數格式錯誤，請確認欄位資料 |
| DEVICE_NOT_FOUND | 查無對應的裝置資料 |
| INVALID_OUTPUT | 寫入失敗，裝置不存在 |
| INVALID_JSON | JSON 解析失敗 |
| INVALID_FIELD | 欄位不存在 |
回應內容
{
"status": "failure",
"errorCode": "SERVER_ERROR",
"message": "伺服器內部錯誤，請稍後再試"
}
文件變更紀錄
