EMS API
文件概述
需求說明
客戶希望能夠讀取設備資料後,進行邊緣運算之後,提供結果給我方呈現在
EMS 畫面上
-
-
系統流程
串接流程圖
串接環境與部署資訊
API 端點資訊
API 功能總覽
動作 | 方法 | 路徑 | 說明 |
取得裝置列表 | GET | /devices | 使用複數命名,代表裝置資源集合 |
取得有效電能的裝置資料 | GET | /devices/kwh | 取得特定裝置(依據 deviceId)之詳細資料 |
取得有效電能日期區間的裝置資料 | GET | /devices/kwh/dateRange | 取得特定裝置(依據 deviceId、日期區間)之詳細資料,限制數量三個月資料(每15分鐘裡最大值) |
取得溫、濕度的裝置資料 | GET | /devices/temperature | 取得特定裝置(依據 deviceId)之詳細資料 |
取得溫、濕度日期區間的裝置資料 | GET | /devices/temperature/dateRange | 取得特定裝置(依據 deviceId、日期區間)之詳細資料,限制數量三個月資料(每15分鐘裡最大值) |
新增計算後資料數據 | POST | /calculations | 將資料上傳至指定裝置,通常為裝置運算後需回傳的結果資料 |
讀取資料 API(GET)說明
請求標頭
傳遞參數
欄位 | 格式 | 必填 | 說明 |
deviceId | String | Required | 裝置唯一識別碼 |
startTime | Datetime | Optional | 資料開始時間 (2025-04-18) |
endTime | Datetime | Optional | 資料結束時間 (2025-05-18) |
JSON
{
"deviceId": "device-002",
"startTime": "2025-04-01 00:00:00",
"endTime": "2025-04-31 23:59:59"
}
回應參數
參數 | 型別 | 說明 |
deviceId | String | 設備ID |
deviceStatus | String | 設備狀態 (on/off) |
timestamp | String | 時間 (ISO8601 格式) |
rawData | Object | 實際設備數值 |
溫、濕度
rawData 實際設備數值 |
參數 | 型別 | 說明 |
temperature | Decimal | 溫度 |
humidity | Decimal | 濕度 |
每小時瓩
rawData 實際設備數值 |
參數 | 型別 | 說明 |
kWh | Decimal | 每小時瓩 |
GET /devices/kwh
回應內容
- 電錶
{
"deviceId": "device-002",
"deviceStatus": "off",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"kWh": 14257.231
}
}
GET /devices/temperature
- 溫溼度感測器
{
"deviceId": "device-001",
"deviceStatus": "on",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"temperature": 26.4,
"humidity": 83.1
}
}
GET /devices/kwh/dateRange
- 電錶(日期區間多筆資料)
{
"deviceId": "device-002",
"deviceStatus": "off",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"kWh": {
"1745481208": 14241.231,
"1745481213": 14244.231,
"1745481219": 14248.231,
"1745481226": 14250.231,
"1745481230": 14253.231,
"1745481237": 14257.231
}
}
}
GET /devices/temperature/dateRange
- 溫溼度感測器(日期區間多筆資料)
{
"deviceId": "device-001",
"deviceStatus": "on",
"timestamp": "2025-04-01T00:00:00+08:00",
"rawData": {
"temperature": {
"1745481315": 25.12,
"1745481319": 25.0,
"1745481324": 25.06,
"1745481329": 25.0,
"1745481334": 24.87,
"1745481340": 25.18
},
"humidity": {
"1745481315": 78.12,
"1745481319": 81.0,
"1745481324": 84.06,
"1745481329": 80.0,
"1745481334": 76.87,
"1745481340": 74.18
}
}
}
上傳資料 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 | 嚴重異常,需處理 |
回應內容
錯誤代碼與說明
錯誤代碼 | 錯誤訊息 |
UNAUTHORIZED | API 金鑰無效或未授權 |
SERVER_ERROR | 伺服器內部錯誤,請稍後再試 |
INVALID_INPUT | 請求參數格式錯誤,請確認欄位資料 |
DEVICE_NOT_FOUND | 查無對應的裝置資料 |
INVALID_OUTPUT | 寫入失敗,裝置不存在 |
INVALID_JSON | JSON 解析失敗 |
INVALID_FIELD | 欄位不存在 |
回應內容
{
"status": "failure",
"errorCode": "SERVER_ERROR",
"message": "伺服器內部錯誤,請稍後再試"
}
文件變更紀錄