總覽
本文建將詳細介紹 Event Dispatching 如何接收 Data Callback。
關於 Event Dispatching 使用要求，請參考Event Dispatching 使用要求 說明。
Required Data
SP 可以通過 Event Dispatching 取得 EU 的裝置數據。
種類①：Data upload
當完成 Event Dispatching 設定後，IoE Platform 將透過閘道器把 EU 的裝置數據上傳至 IoE Platform 暫存，並同步將其寄送至 SP 指定的 Endpoint。
種類②：Device Data Acquire (use with Event Dispatching)
若 SP 想取得即時資料，則可透過呼叫 Data Point Service（DPS）的「Device Data Acquire」API，下達指令取得特定裝置的 scope 資訊。
IoE Platform 將於收到上述指令後對 GW 下達指令，並於 GW 上傳取得的裝置資料後，將其寄送至 SP 指定的 Event Dispatching Endpoint。
Event Dispatching 請求
當執行要求的意圖（Intent）被滿足時，IoE Platform 將以 HTTPS 對 SP 指定的 Event Dispatching Endpoint 送出 POST 請求。
格式①
下列狀況下，IoE Platform 將以 Node Device 為單位，以物件（Object）格式彙整符合執行要求的裝置數據後送出。
-
Data upload：GW 定期上傳裝置資料時
-
Device Data Acqurie：呼叫 Key｜數據存取 | ② Device Data Acquire API 時
請求體格式
|
參數 |
說明 |
類型 |
|---|---|---|
|
version |
Event Dispatching 請求體格式的版號 |
字串 |
|
eventId |
通知事件的唯一識別碼 |
字串 |
|
eventType |
通知事件的類型 |
字串 |
|
data |
通知事件的內容 |
JSON 物件 |
|
dsn |
Node Device 關聯後，IoE Platfrom 配發的唯一識別碼 |
字串 |
|
associationId |
Node Device 關聯後，IoE Platfrom 配發的唯一識別碼
|
字串 |
|
deviceUuid |
Node Device 關聯後，IoE Platfrom 配發的唯一識別碼
|
字串 |
|
value |
數據內容 |
JSON 物件陣列 |
|
scope |
數據的識別名稱 |
字串 |
|
value |
數據值 |
字串 |
|
generatedAt |
數據產生的時間戳（單位為毫秒） |
Unix 時間戳 |
|
uploadedAt |
數據上傳至 IoE Platform 的時間戳（單位為毫秒） |
Unix 時間戳 |
|
generatedAt |
事件產生的時間戳（單位為毫秒） |
Unix 時間戳 |
請求體範例
{
"version": "1",
"eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
"eventType": "datapoint",
"data": {
"dsn": "VG69D20093999",
"associationId": "a363b8cc-c9a7-499a-95ab-d9c2817f4ea8"
"deviceUuid": "a363b8cc-c9a7-499a-95ab-d9c2817f4ea8"
"values": [{
"scope": "instanceElectricity",
"value": "34.4",
"generatedAt": 1670575442000,
"uploadedAt": 1670575442100
}],
},
"generatedAt": 1670575442000
}
格式②
下列狀況下，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 |
呼叫的指令種類
|
字串 |
|
publishedAt |
IoE Platform 送出指令的時間戳（單位為毫秒） |
Unix 時間戳 |
|
scopes |
取得資料的內容 |
JSON 物件陣列 |
|
name |
數據的識別名稱 |
字串 |
|
result |
指令的實施結果
|
字串 |
|
value |
執行指令而取到的資料數值 |
字串 |
|
error |
指令實施失敗時回覆的錯誤訊息 |
字串 |
|
errorCode |
指令實施失敗時回覆的錯誤代碼 |
字串 |
|
generatedAt |
事件產生的時間戳（單位為毫秒） |
Unix 時間戳 |
請求體範例
{
"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 指定的 Event Dispatching Endpoint。
請留意，各閘道器上傳資料的時間皆不相同。
資料乘載量則受可存取閘道器的數量、欲取得數據的裝置數量、數據取得頻率影響。
存取數據時請務必考慮雲端服務器的乘載量。
2. 無法提供服務
NextDrive 不保證 SP 可透過 Event Dispatching 取得所有數據。
基於部分不可抗力原因，NexDrive 將無法透過 Event Dispatching 提供數據。
如有上述情形，SP 仍然可透過 “Data Retrieval” API 取得未送出的數據。