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

總覽

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

Device Status Callback

SP 可以通過 Webhook Service 取得 EU 的終端裝置狀態。
當完成 Webhook Service 設定後，IoE Platform 將在已訂閱 Service EU 裝置狀態改變時，將裝置的狀態資訊寄送至 SP 的 Webhook Service。

Webhook 請求

當下列執行要求意圖（Intent）被滿足時，IoE Platform 將以 HTTPS 對 SP 的 Webhook Service 送出 POST 請求。
該請求的主體（Body）將包括 Service 訂閱用戶能源閘道器下的設備列表，並以物件陣列（Object Array）彙整符合執行要求的裝置狀態。

GATEWAY_ASSOCIATED：當已訂閱 Service 的 EU，對能源閘道器完成關聯時
GATEWAY_DISSOCIATED：當已訂閱 Service 的 EU，對能源閘道器解除關聯時
DEVICE_PAIRED：當已訂閱 Service 的 EU，對裝置完成配對時
DEVICE_UNPAIRED：當已訂閱 Service 的 EU，對裝置解除配對時
GATEWAY_ONLINE：當已訂閱 Service 的 EU 的能源閘道器，從離線狀態變成上線狀態時
GATEWAY_OFFLINE：當已訂閱 Service 的 EU 的能源閘道器，從上線狀態變成離線狀態時
DEVICE_ONLINE：當已訂閱 Service 的 EU 的裝置，從離線狀態變成上線狀態時
DEVICE_OFFLINE：當已訂閱 Service 的 EU 的裝置，從上線狀態變成離線狀態時
DEVICE_NAME_CHANGED：當已訂閱 Service 的 EU，更新其裝置名稱時

請求主體

參數	說明	類型
triggerReason	GATEWAY_ASSOCIATED GATEWAY_DISSOCIATED DEVICE_PAIRED DEVICE_UNPAIRED GATEWAY_ONLINE GATEWAY_OFFLINE DEVICE_ONLINE DEVICE_OFFLINE DEVICE_NAME_CHANGED	字串
userId	EU 的 Id	字串
gateway	閘道器的物件資訊	物件
uuid	閘道器 uuid	字串
status	"ONLINE"：能源閘道器已與 IoE Platform 連線 "OFFLINE"：能源閘道器未與 IoE Platform 斷線	字串
devices	與閘道器關聯的裝置	物件陣列
uuid	裝置 uuid	字串
model	NextDrive 定義的裝置類型	字串
name	EU 定義的裝置名稱	字串
status	"ONLINE"：裝置已與閘道器連線 "OFFLINE"：裝置未與閘道器連線	字串

請求主體（以 GATEWAY_ASSOCIATED 為例）

訂閱用戶若完成能源閘道器配對（尚未與任何裝置配對），配對完成的能源閘道器資訊，將以 Callback 方式送出。

{
  "triggerReason": "GATEWAY_ASSOCIATED",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": []
  }
}

※ 關於其他 triggerReason 的請求主體範例，詳見附件說明。

使用限制

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

附件

GATEWAY_DISSOCIATED

訂閱用戶若解除關聯能源閘道器，其下的所有設備也將同時被解除配對。
此時，解除關聯前最後的裝置狀態資訊，將以 Callback 方式送出。

{
  "triggerReason": "GATEWAY_DISSOCIATED",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}

DEVICE_PAIRED

訂閱用戶若完成裝置配對，配對完成的裝置資訊將納入 device 陣列中，以 Callback 方式送出。

{
  "triggerReason": "DEVICE_PAIRED",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}

DEVICE_UNPAIRED

訂閱用戶若解除裝置配對，解除配對的裝置資訊將從 device 陣列中移除，以 Callback 方式送出。

{
  "triggerReason": "DEVICE_UNPAIRED",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        ...
      }
    ]
  }
}

GATEWAY_ONLINE

當能源閘道器從離線狀態轉換成連線狀態時，當前的設備狀態將納入 device 陣列中，以 Callback 方式送出。

{
  "triggerReason": "GATEWAY_ONLINE",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "onlineAt": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}

GATEWAY_OFFLINE

當能源閘道器從連線狀態轉換成離線狀態時，能源閘道器離線前最後的裝置狀態資訊，將以 Callback 方式送出。

{
  "triggerReason": "GATEWAY_OFFLINE",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "onlineAt": 1667964855000,
  "offlineAt": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "OFFLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}

DEVICE_ONLINE

當裝置從離線狀態轉換成連線狀態時，連線裝置的狀態資訊將納入 device 陣列中，以 Callback 方式送出。

{
  "triggerReason": "DEVICE_ONLINE",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}

DEVICE_OFFLINE

當裝置從連線狀態轉換成離線狀態時，離線裝置的狀態資訊將納入 device 陣列中，以 Callback 方式送出。

{
  "triggerReason": "DEVICE_OFFLINE",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "OFFLINE"
      },
      {
        ...
      }
    ]
  }
}

DEVICE_NAME_CHANGED

當訂閱用戶更新裝置名稱時，裝置名稱將於 device 陣列中更新，以 Callback 方式送出。

{
  "triggerReason": "DEVICE_NAME_CHANGED",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventTime": 1667964856000,
  "gateway": {
    "uuid": "ca14acbd-51e3-4ec9-8751-746c300c759e",
    "status": "ONLINE",
    "devices": [
      {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model": "SmartMeter",
        "name": "string",
        "status": "ONLINE"
      },
      {
        ...
      }
    ]
  }
}