目錄表

EMS API

文件概述

需求說明

  1. 客戶希望能夠讀取設備資料後,進行邊緣運算之後,提供結果給我方呈現在 EMS 畫面上
  2. 我方提供 API 服務供對方進行呼叫

系統流程

串接流程圖

串接環境與部署資訊

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)說明

請求標頭

傳遞參數

欄位 格式 必填 說明
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 嚴重異常,需處理

回應內容

{
  "status": "success"
}

錯誤代碼與說明

錯誤代碼 錯誤訊息
UNAUTHORIZED API 金鑰無效或未授權
SERVER_ERROR 伺服器內部錯誤,請稍後再試
INVALID_INPUT 請求參數格式錯誤,請確認欄位資料
DEVICE_NOT_FOUND 查無對應的裝置資料
INVALID_OUTPUT 寫入失敗,裝置不存在
INVALID_JSON JSON 解析失敗
INVALID_FIELD 欄位不存在

回應內容

{
  "status": "failure",
  "errorCode": "SERVER_ERROR",
  "message": "伺服器內部錯誤,請稍後再試"
}

文件變更紀錄