API 核心功能
概述
本開放平台API提供設備時序數據與數倉數據的全鏈路服務，支援透過安全的RSA令牌加密機制進行身份驗證。核心功能涵蓋設備數據推播、詳情查詢、即時與歷史點位數據獲取，以及數據集的匯入與查詢，為第三方系統整合提供標準化、安全可靠的數據介面。
提示
時序數據：一系列帶時間戳的數據點，用於描述設備在特定時間點的狀態或測量值。它是物聯網領域最常見的數據類型。
數倉數據：儲存在數據倉儲中的、通常經過清洗、聚合後的業務數據或主數據，可用於更複雜的分析和報表。
開始之前
權限 配置
為確保以下操作流程正常進行，請您確認是否擁有專案管理員權限。
令牌加密傳輸指南
本指南旨在詳細介紹如何在我們的開放平台中安全地使用 RSA 加密演算法進行令牌（Token）的加密傳輸。透過遵循本指南，您將能夠確保敏感數據在客戶端與伺服器之間的傳輸過程中得到最高級別的保護。
具體的操作詳見下文 ->
令牌加密流程
- 產生金鑰
開發者需要在中台應用中申請令牌，系統會產生金鑰對，開發者下載令牌資訊（資訊包含金鑰 ID、金鑰 Key 和公鑰）,下載資訊將用於加密令牌，私鑰則用於解密。 - 令牌申請，下載
1、進入設備管理
進入設備管理，操作詳見設備管理
2、令牌申請與下載
新增或下載令牌，操作詳見令牌下載 - API 介面說明
系統透過安全機制獲取的令牌（Token）資訊，利用 RSA 加密演算法進行加密處理，產生加密後的密文（Ciphertext）。隨後，將此密文嵌入至 API（應用程式介面）請求的 HTTP 頭部（Header）中，作為認證或授權資訊的一部分，進而發起 API 請求。此過程確保了令牌資訊在傳輸過程中的機密性和安全性，防止了敏感資訊的洩露（加密方法可請參考下面範例程式碼）。提示密文（Ciphertext）指的是經過加密演算法處理後的、無法被直接閱讀或理解的混亂數據。與之相對的是明文（Plaintext），也就是加密前的原始、可讀的數據。
範例程式碼
Python 範例檔案
JAVA 範例檔案
Golang 範例檔案
.Net 範例檔案
Node.js 範例檔案
常見請求錯誤碼
| 編碼 | 描述 |
|---|---|
| 401 | accesstoken 過期，需要重新獲取 |
| 404 | 介面地址錯誤 |
| 428 | 使用者或租戶不存在 |
| 429 | 使用者未註冊 |
| 500 | 伺服器內部錯誤 |
| 503 | 服務忙，稍後重試 |
| 1000 | 數據***已存在 |
設備時序數據
設備時序數據推播
提示
時序數據指一系列帶時間戳的數據點，用於描述設備在特定時間點的狀態或測量值。它是物聯網領域最常見的數據類型。
可接入設備上報的時序數據，一次可推播多個設備，單次請求數據總數不可超過1000 條
URL：{neuron domain}/neurongateway/openapi/dataPlatform/openapi
HTTP 請求方式: Post
請求體類型: 陣列
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
陣列單物件說明：
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| time | string | 否 | 設備數據採集時間 |
| equipmentName | string | 是 | 設備名稱 |
| functionType | string | 是 | 設備點位名稱 |
| buildingName | string | 是 | 設備所在樓宇名稱（需同設備註冊樓宇名稱一致） |
| devEui | string | 否 | IoT 設備唯一標識 |
| value | double | 否 | 設備點位數字類型值 （value 和 reading 二選一） |
| reading | string | 否 | 設備點位數字元類型值（value 和 reading 二選一） |
| unit | string | 否 | 設備點位單位 |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
返回錯誤碼
詳見常見請求錯誤碼
設備詳情查詢
提示
可查詢單個設備詳情資訊
URL: {neuron domain}/neurongateway/openapi/device/v1/mn/{devEui}
HTTP 請求方式: Get
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| devEui | string | 是 | IoT 設備唯一標識 |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
| data | object | 設備詳情物件 |
設備詳情data物件欄位說明
| 欄位名稱 | 描述 |
|---|---|
| name | 設備名稱 |
| alias | 設備別名 |
| equModel | 設備物模型 |
| points | 單個設備對應的設備點位資訊（設備 points 下單個物件欄位說明） |
| devEUI | IoT 設備唯一標識 |
| location | 設備註冊位置資訊 |
| isOnline | 設備是否在線（True 表示在線，False 表示離線） |
| descriptions | 設備描述 |
| isIot | 是否 IoT 設備（True 是 IoT 設備，False 非 IoT 設備） |
| buildingName | 設備註冊樓宇名稱 |
設備詳情points陣列單個物件欄位說明
| 欄位名稱 | 描述 |
|---|---|
| type | 設備點位名稱 |
| unit | 設備點位單位 |
| bmsId | 非 IoT 設備點位 ID |
| control | 是否支援反控（True 可反控，False 不可反控） |
返回錯誤碼
詳見常見請求錯誤碼
設備列表查詢
提示
可查詢目前租戶下可查看的所有設備資訊
URL: {neuron domain}/neurongateway/openapi/device/v1/mn/page
HTTP 請求方式: Get
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| current | int | 是 | 目前頁 |
| size | int | 是 | 每頁條數 |
| name | string | 否 | 設備名稱（模糊匹配） |
| devEui | string | 否 | IoT 設備唯一標識（精確匹配） |
| buildingName | string | 否 | 設備註冊時填寫的樓宇名稱（精確匹配） |
| equModel | string | 否 | 設備物模型名稱（精確匹配） |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
| data | object | 設備列表物件（total：總條數，size：每頁條數，current：目前頁，records：設備數據） |
設備數據records下單個物件欄位說明
| 欄位名稱 | 描述 |
|---|---|
| name | 設備名稱 |
| alias | 設備別名 |
| equModel | 設備物模型 |
| points | 單個設備對應的設備點位資訊（設備 points 下單個物件欄位說明） |
| devEUI | IoT 設備唯一標識 |
| location | 設備註冊位置資訊 |
| isOnline | 設備是否在線（True 表示在線，False 表示離線） |
| descriptions | 設備描述 |
| isIot | 是否 IoT 設備（True 是 IoT 設備，False 非 IoT 設備） |
| buildingName | 設備註冊樓宇名稱 |
設備points下單個物件欄位說明
| 欄位名稱 | 描述 |
|---|---|
| type | 設備點位名稱 |
| unit | 設備點位單位 |
| bmsId | 非IoT設備點位ID |
| control | 是否支援反控（True可反控，False不可反控） |
返回錯誤碼
詳見請求錯誤碼
設備點位最新值查詢
提示
可查詢目前租戶下可查看的所有設備資訊
URL: {neuron domain}/neurongateway/openapi/device/v1/realtime/{devEui}/values
HTTP 請求方式: Get
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| devEui | string | 否 | IoT 設備唯一標識（精確匹配） |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
| data | array | 設備點位最新值 |
設備data數據中單個物件欄位說明
| 欄位名稱 | 描述 |
|---|---|
| eqName | 設備名稱 |
| alias | 設備別名 |
| equModel | 設備物模型 |
| devEUI | IoT 設備唯一標識 |
| state | 設備擴展狀態碼 |
| isOnline | 設備是否在線（True 表示在線，False 表示離線） |
| descriptions | 設備描述 |
| pid | 設備位置資訊（專案） |
| building | 設備註冊樓宇名稱 |
| floor | 設備註冊樓層名稱 |
| room | 設備註冊房間名稱 |
| editVos | 設備點位列表 |
返回錯誤碼
詳見請求錯誤碼
設備點位歷史值查詢
提示
可查詢某個設備下單個或所有點位的某段時間的數據值（時間區間僅可查詢一週內的數據）
URL: {neuron domain}/neurongateway/openapi/device/v1/realtime/history
HTTP 請求方式: Post
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| equipmentName | string | 是 | 設備名稱（精確匹配） |
| functionType | string | 否 | 設備點位名稱 |
| startTime | datatime | 否 | 開始時間 |
| endTime | datatime | 否 | 結束時間 |
| field | string | 是 | 設備點位值類型（VALUE 為數值型，READING 為字元型） |
| equModel | string | 否 | 設備物模型名稱（精確匹配） |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
| data | array | 設備點位數值物件 |
設備data陣列單個欄位說明
| 欄位名稱 | 描述 |
|---|---|
| time | 數據採集時間 |
| equipmentName | 設備名稱 |
| buildingName | 設備註冊樓宇資訊 |
| functionType | 單個設備點位名稱 |
| devEUI | IoT 設備唯一標識 |
| value | 設備數字類型值 |
| reading | 設備字元類型值 |
| unit | 設備點位單位 |
返回錯誤碼
詳見請求錯誤碼
數倉數據
數據推播
提示
數倉數據指儲存在數據倉儲中的、通常經過清洗、聚合後的業務數據或主數據，可用於更複雜的分析和報表。
可接入數據集數據（推播的欄位和數據類型需和數據集配置對應），一次可推播多條（單次請求數據總數不可超過 1000 條）
URL: {neuron domain}/neurongateway/openapi/dataset/v1/{templateCode}
HTTP 請求方式: Post
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
| X-Param-ProjectId | string | Header | 是 | 平台專案 ID |
請求體類型: 陣列
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| datasetName | string | 是 | 數據集 ID |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
返回錯誤碼
詳見請求錯誤碼
數據查詢
提示
可查詢某個設備下單個或所有點位的某段時間的數據值（時間區間僅可查詢一週內的數據）
URL: {neuron domain}/neurongateway/openapi/dataset/v1/{templateCode}
HTTP 請求方式: Get
身份驗證: 請求頭欄位說明（加密方法詳見API 呼叫 Demo）
| 欄位名稱 | 欄位類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | 是 | 金鑰 ID |
| X-Source-SecretKey | string | Header | 是 | 金鑰加密文字 |
| X-Param-ProjectId | string | Header | 是 | 平台專案 ID |
請求參數
| 欄位名稱 | 欄位類型 | 是否必傳 | 描述 |
|---|---|---|---|
| equipmentName | string | 是 | 設備名稱（精確匹配） |
| functionType | string | 否 | 設備點位名稱 |
| startTime | datatime | 否 | 開始時間 |
| endTime | datatime | 否 | 結束時間 |
| field | string | 是 | 設備點位值類型（VALUE 為數值型，READING 為字元型） |
| equModel | string | 否 | 設備物模型名稱（精確匹配） |
返回結果欄位說明
| 欄位名稱 | 欄位類型 | 描述 |
|---|---|---|
| code | int | 請求響應碼，200 表示成功 |
| message | string | 系統訊息 |
| isSuccess | boolean | 成功返回 True, 失敗返回 False |
| data | array | 設備點位數值物件 |
設備data陣列單個欄位說明
| 欄位名稱 | 描述 |
|---|---|
| time | 數據採集時間 |
| equipmentName | 設備名稱 |
| buildingName | 設備註冊樓宇資訊 |
| functionType | 單個設備點位名稱 |
| devEUI | IoT 設備唯一標識 |
| value | 設備數字類型值 |
| reading | 設備字元類型值 |
| unit | 設備點位單位 |
返回錯誤碼
詳見請求錯誤碼