WS format｜Required Data | 能源物聯網解決方案

總覽

本文建將詳細介紹 Webhook Service 如何接收 Data Callback。
關於 Webhook Service 使用要求，請參考 Webhook Service 使用要求說明。

Required Data

SP 可以通過 Webhook Service 取得 EU 的終端裝置數據。
當完成 Webhook Service 設定後，IoE Platform 將透過閘道器把 EU 的裝置數據上傳至 IoE Platform 暫存，並同步將其寄送至 SP 的 Webhook Service。

image2020-11-4_15-26-32.png?version=1&modificationDate=1642071566681&cacheVersion=1&api=v2

Webhook 請求

當執行要求的意圖（Intent）被滿足時，IoE Platform 將以 HTTPS 對 SP 的 Webhook Service 送出 POST 請求。

格式①

下列狀況下，IoE Platform 將以 Node Device 為單位，以物件陣列（Object Array）格式彙整符合執行要求的裝置數據後送出。

Data upload：GW 定期上傳裝置資料時
Device Data Acqurie：呼叫 Key｜數據存取 | ② Device Data Acquire API 時

請求主體

參數	說明	類型
data	裝置數據	陣列
deviceUuid	裝置的 uuidd	字串
model	NextDrive 定義的裝置類型	字串
scope	數據項目 (※)	字串
value	數據的數值	字串
generatedTime	閘道器取得數據的時間戳（單位為毫秒）	Unix 時間戳
uploadedTime	數據上傳至 IoE Platform 的時間戳（單位為毫秒）	Unix 時間戳

請求主體範例

{

    "data": [{
        "deviceUuid": "49423130-312d-3030-3031-7802b78001c2",
        "model": "SolarPW",
        "scope": "instanceElectricity",
        "value": "225",
        "generatedTime": 1587344472692,
        "uploadedTime": 1587346904016
    },
    {
        "deviceUuid": "49423130-312d-3030-3031-7802b78001c2",
        "model": "SolarPW",
        "scope": "instanceElectricity",
        "value": "265",
        "generatedTime": 1587344545566,
        "uploadedTime": 1587346904016
    },... ]
}

格式②

下列狀況下，IoE Platform 將以 Node Device 的 Scope 為單位，以物件（Object）格式彙整符合執行要求的裝置數據後送出。

Device Data Acqurie：呼叫 Token｜資料存取 | ① Device Data Acquire (request) API 時

請求體格式

參數	說明	類型
version	Event Dispatching 請求體格式的版號	字串
eventId	通知事件的唯一識別碼	字串
eventType	通知事件的類型	字串
data	通知事件的內容	JSON 物件
dsn	Node Device 關聯後，IoE Platfrom 配發的唯一識別碼	字串
action	呼叫的指令種類 read：讀取指令	字串
publishedAt	IoE Platform 送出指令的時間戳（單位為毫秒）	Unix 時間戳
scopes	取得資料的內容	JSON 物件陣列
name	數據的識別名稱	字串
result	指令的實施結果 success：成功 failure：失敗	字串
value	執行指令而取到的資料數值	字串
error	指令實施失敗時回覆的錯誤訊息	字串
errorCode	指令實施失敗時回覆的錯誤代碼	字串
generatedAt	事件產生的時間戳（單位為毫秒）	Unix 時間戳

請求體範例

JSON

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "scopeCommandResult",
  "data": {
    "dsn": "VG69D20093999",
    "action": "read",
    "publishedAt": 1689265515155,
    "scopes": [
      {
        "name": "reverseUsage",
        "result": "success",
        "value": "1.600000",
        "error": "<error message>", // optional
        "errorCode": "<error code>"   // optional
      }
    ]
  },
  "generatedAt": 1670575442000
}

使用限制

1.　Callback 頻率及資料乘載量

閘道器將依據 SP 定義的頻率（upload interval）上傳數據（預設為每10分鐘1次）。
當 IoE Platform 取得閘道器上傳的數據時，同步寄送各閘道器上傳的數據封包至 SP 的 Webhook Service。
請留意，各閘道器上傳資料的時間皆不相同。

資料乘載量則受可存取閘道器的數量、欲取得數據的裝置數量、數據取得頻率影響。
存取數據時請務必考慮雲端服務器的乘載量。

2.　無法提供服務

NextDrive 不保證 SP 可透過 Data Callback 取得所有數據。
基於部分不可抗力原因，NexDrive 將無法透過 Data Callback 提供數據。
如有上述情形，SP 仍然可透過 “Data Retrieval” API 取得未送出的數據。

總覽