====== EMS API ======
===== 文件概述 =====
==== 需求說明 ====
- 客戶希望能夠讀取設備資料後，進行邊緣運算之後，提供結果給我方呈現在 EMS 畫面上
- 我方提供 API 服務供對方進行呼叫
- 參考文件：[[https://hackmd.io/@bclin087/Hk6eKCsRJl]]
===== 系統流程 =====
==== 串接流程圖 ====
{{public:fronteco:api.diagram.png}}
===== 串接環境與部署資訊 =====
==== API 端點資訊 ====
^ 項目 ^ 資訊 ^
| 正式 API 網址 | https://ems.yo-win.com:81/api/v1 |
| 測試 API 網址 | https://emst.yo-win.com:81/api/v1 |
| API Key（範例） | ''RnJpIE5vdiAwMyAyMDIzIDE1OjIwOjMwG'' |
==== 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）說明 =====
==== 請求標頭 ====
* x-api-key：''由 EMS 提供授權碼''
==== 傳遞參數 ====
^ 欄位 ^ 格式 ^ 必填 ^ 說明 ^
| 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）說明 =====
==== 請求標頭 ====
* x-api-key：''由 EMS 提供授權碼''
==== 上傳參數====
^ 參數 ^ 型別 ^ 說明 ^
| 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 | 嚴重異常，需處理 |
==== 回應內容 ====
{
"status": "success"
}
===== 錯誤代碼與說明 =====
^ 錯誤代碼 ^ 錯誤訊息 ^
| UNAUTHORIZED | API 金鑰無效或未授權 |
| SERVER_ERROR | 伺服器內部錯誤，請稍後再試 |
| INVALID_INPUT | 請求參數格式錯誤，請確認欄位資料 |
| DEVICE_NOT_FOUND | 查無對應的裝置資料 |
| INVALID_OUTPUT | 寫入失敗，裝置不存在 |
| INVALID_JSON | JSON 解析失敗 |
| INVALID_FIELD | 欄位不存在 |
==== 回應內容 ====
{
"status": "failure",
"errorCode": "SERVER_ERROR",
"message": "伺服器內部錯誤，請稍後再試"
}
===== 文件變更紀錄 =====
* **2025-04-17** 建立此頁，設定基本雛型架構
* **2025-04-18** 經過雙方會談後，整理出較接近的需求版本，並提供較細節的定義內容