ED format｜Device Status | 能源物聯網解決方案

總覽

本文建將詳細介紹 Event Dispatching 如何接收 Device Status Callback。
關於 Event Dispatching 使用要求，請參考 Event Dispatching 使用要求說明。

Device Status Callback

SP 可以通過 Event Dispatching 取得 EU 的裝置狀態。
當完成 Event Dispatching 設定後，IoE Platform 將會於 Service 訂閱用戶的裝置狀態改變時，將裝置狀態資訊寄送至 SP 指定的 Endpoint。

Event Dispatching 請求

當下列執行要求意圖（Intent）被滿足時，IoE Platform 將以 HTTPS 對 SP 指定的 Event Dispatching Endpoint 送出 POST 請求。
請求體（Request Body）將依據通知事件的類型，以物件（Object）格式彙整符合執行要求的裝置狀態並送出。
通知事件類型與內容彙整如下列說明：

registration 事件類型

請求體格式

參數	說明	類型
version	Event Dispatching 請求體格式的版號	字串
eventId	通知事件的唯一識別碼	字串
eventType	通知事件的類型	字串
data	通知事件的內容	JSON 物件
action	裝置的通知事件，包含： “REGISTRATION”：Single Device 註冊 “DEREGISTRATION”：Single Device 解註冊	字串
dsn	Single Device 註冊後，IoE Platfrom 配發的唯一識別碼	字串
registrationId	Single Device 註冊後，IoE Platfrom 配發的唯一識別碼 `若裝置為 Gateway Device，等同於 gatewayUuid`	字串
name	EU 定義的裝置名稱	字串
userId	EU 的唯一識別碼	字串
model	註冊裝置的硬體型號	字串
generatedAt	事件產生的時間戳（單位為毫秒）	Unix 時間戳

請求體範例

Single Device / Gateway Device Registration

Service 訂閱用戶若完成 Single Device 或 Gateway Device 註冊，該裝置的註冊資訊將以 Callback 方式送出。
※　Webhook Service 中 GATEWAY_ASSOCIATED 的對照事件。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "registration",
  "data": {
    "action": "REGISTRATION",
    "dsn": "ND69D20093999",
    "registrationId": "4e445049-5849-5555-4944-24718901a594",
    "name": "device name",
    "userId": "6107ae19-3b6f-47e2-b2b9-8627dabe89d3",
    "model": "Atto"
  },
  "generatedAt": 1670575442000
}

Single Device / Gateway Device Deregistration

Service 訂閱用戶若解除 Single Device 或 Gateway Device 註冊，該裝置的註冊解除資訊將以 Callback 方式送出。
※1 Webhook Service 中 GATEWAY_DISSOCIATED 的對照事件。
※2 Gateway Device 解除註冊後，關聯在該 Gateway Device 下的裝置也將同時被解除關聯。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "registration",
  "data": {
    "action": "DEREGISTRATION",
    "dsn": "ND69D20093999",
    "registrationId": "4e445049-5849-5555-4944-24718901a594",
    "name": "device name",
    "userId": "6107ae19-3b6f-47e2-b2b9-8627dabe89d3",
    "model": "Atto"
  },
  "generatedAt": 1670575442000
}

association 事件類型

請求體格式

參數	說明	類型
version	Event Dispatching 請求體格式的版號	字串
eventId	通知事件的唯一識別碼	字串
eventType	通知事件的類型	字串
data	通知事件的內容	JSON 物件
action	裝置的通知事件，包含： “ASSOCIATION”：Node Device 關聯 “DISSOCIATION”：Node Device 解關聯	字串
dsn	Single Device 註冊後，IoE Platfrom 配發的唯一識別碼	字串
registrationId	Single Device 註冊後，IoE Platfrom 配發的唯一識別碼 `若裝置為 Gateway Device，等同於 gatewayUuid`	字串
userId	EU 的唯一識別碼	字串
nodeDevices	Node Device 的關聯內容	JSON 物件陣列
name	EU 定義的裝置名稱	字串
dsn	Node Device 關聯後，IoE Platfrom 配發的唯一識別碼	字串
associationId	Node Device 關聯後，IoE Platfrom 配發的唯一識別碼 `等同於 gatewayUuid`	字串
model	關聯裝置的硬體型號	字串
generatedAt	事件產生的時間戳（單位為毫秒）	Unix 時間戳

請求體範例

Node Device Association

Service 訂閱用戶若完成 Node Device 關聯，該裝置的關聯資訊將以 Callback 方式送出。
※ Webhook Service 中 DEVICE_PAIRED 的對照事件。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "association",
  "data": {
    "action": "ASSOCIATION",
    "dsn": "ND69D20093999",
    "registrationId": "4e445049-5849-5555-4944-24718901a594",
    "userId": "6107ae19-3b6f-47e2-b2b9-8627dabe89d3",
    "nodeDevices": [
       {
         "name": "node-device name",
         "dsn": "VG69D20093999",
         "associationId": "31445049-5849-5555-4944-24718901a594",
         "model": "AirCon"
       }
    ]
  },
  "generatedAt": 1670575442000
}

Node Device Dissociation

Service 訂閱用戶若解除 Node Device 關聯，該裝置的關聯解除資訊將以 Callback 方式送出。
※　Webhook Service 中 DEVICE_UNPAIRED 的對照事件。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "association",
  "data": {
    "action": "DISSOCIATION",
    "dsn": "ND69D20093999",
    "registrationId": "4e445049-5849-5555-4944-24718901a594",
    "userId": "6107ae19-3b6f-47e2-b2b9-8627dabe89d3",
    "nodeDevices": [
       {
         "name": "node-device name",
         "dsn": "VG69D20093999",
         "associationId": "31445049-5849-5555-4944-24718901a594",
         "model": "AirCon"
       }
    ]
  },
  "generatedAt": 1670575442000
}

connection 事件類型

請求體格式

參數	說明	類型
version	Event Dispatching 請求體格式的版號	字串
eventId	通知事件的唯一識別碼	字串
eventType	通知事件的類型	字串
data	通知事件的內容	JSON 物件
dsn	狀態改變之裝置的唯一識別碼	字串
status	裝置改變後的狀態，包含： “ONLINE”：裝置從 offline 變成 online “OFFLINE”：裝置從 online 變成 offline	字串
generatedAt	事件產生的時間戳（單位為毫秒）	Unix 時間戳

請求體範例

Device Online

當 Service 訂閱用戶的裝置，從離線狀態轉換成連線狀態時，該裝置的狀態資訊將以 Callback 方式送出。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "connection",
  "data": {
    "dsn": "VG69D20093999",
    "status": "ONLINE"
  },
  "generatedAt": 1670575442000
}

Device Offline

當 Service 訂閱用戶的裝置，從連線狀態轉換成離線狀態時，該裝置的狀態資訊將以 Callback 方式送出。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "connection",
  "data": {
    "dsn": "VG69D20093999",
    "status": "OFFLINE"
  },
  "generatedAt": 1670575442000
}

attribute 事件類型

請求體格式

參數	說明	類型
version	Event Dispatching 請求體格式的版號	字串
eventId	通知事件的唯一識別碼	字串
eventType	通知事件的類型	字串
data	通知事件的內容	JSON 物件
action	裝置的通知事件 ”DEVICE_NAME_CHANGED”：裝置名稱變更	字串
dsn	名稱變更裝置的唯一識別碼	字串
name	變更後的名稱資訊	字串
userId	EU 的唯一識別碼	字串
model	名稱變更裝置的硬體型號	字串
deviceType	此次名稱變更裝置的裝置類型	字串
generatedAt	事件產生的時間戳（單位為毫秒）	Unix 時間戳

請求體範例

Node Device Name Changed

當 Service 訂閱用戶更新裝置名稱時，該裝置更新後的名稱將以 Callback 方式送出。

{
  "version": "1",
  "eventId": "1c97b7de-8852-4a55-a2eb-d7982b3231f9",
  "eventType": "attribute",
  "data": {
    "action": "DEVICE_NAME_CHANGED"
    "dsn": "VG69D20093999",
    "name": "new name",
    "userId": "6107ae19-3b6f-47e2-b2b9-8627dabe89d3",
    "model": "AirCon",
    "deviceType": "node-device"
  },
  "generatedAt": 1670575442000
}

使用限制

NextDrive 不保證 SP 可透過 Event Dispatching 取得所有裝置的狀態資訊。
基於部分不可抗力原因，NexDrive 將無法透過 Event Dispatching 提供資訊。
如有上述情形，SP 仍然可透過「Get Device List」API 取得 API 呼叫當下的裝置狀態資訊。