OpenAPI 指南
令牌加密傳輸指南
本指南旨在詳細介紹如何在我們的開放平台中安全地使用 RSA 加密算法進行令牌（Token）的加密傳輸。通過遵循本指南，您將能夠確保敏感數據在客戶端與伺服器之間的傳輸過程中得到最高級別的保護。
令牌加密流程
- 生成密鑰對
開發者需要在中台應用中申請令牌，系統會生成密鑰對。開發者下載令牌信息（信息包含密鑰 ID、密鑰 Key 和公鑰），這些信息將用於加密令牌，私鑰則用於解密。 - 令牌申請與下載
- API 接口說明
系統通過安全機制獲取的令牌（Token）信息，利用 RSA 加密算法進行加密處理，生成加密後的密文（Ciphertext）。隨後，將此密文嵌入至 API（應用程式接口）請求的 HTTP 頭部（Header）中作為認證或授權信息的一部分，進而發起 API 請求。此過程確保令牌信息在傳輸過程中的機密性和安全性，防止敏感信息的洩露（加密方法參考示例代碼）。
示例代碼
常見請求錯誤碼
| 編碼 | 描述 |
|---|---|
| 401 | accesstoken 過期，需要重新獲取 |
| 404 | 接口地址錯誤 |
| 428 | 用戶或租戶不存在 |
| 429 | 用戶未註冊 |
| 500 | 伺服器內部錯誤 |
| 503 | 服務繁忙，稍後重試 |
| 1000 | 數據***已存在 |
設備時序數據
設備時序數據推送
提示
可接入設備上報的時序數據，一次可推送多個設備，單次請求數據總數不可超過 1000 條。
URL: /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: /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 | 單個設備的功能點列表（詳見下方字段說明） |
| devEUI | IoT 設備唯一標識 |
| location | 設備註冊位置 |
| isOnline | 設備是否在線（True 為在線，False 為離線） |
| descriptions | 設備描述 |
| isIot | 是否為 IoT 設備（True 是 IoT 設備，False 為非 IoT 設備） |
| buildingName | 設備註冊樓宇名稱 |
設備點位 points 單個對象字段說明
| 字段名稱 | 描述 |
|---|---|
| type | 設備點位名稱 |
| unit | 設備點位單位 |
| bmsId | 非 IoT 設備點位 ID |
| control | 是否支持反控（True 支持，False 不支持） |
返回錯誤碼
詳見常見請求錯誤碼
設備列表查詢
提示
可查詢當前租戶下所有設備的信息。
URL: /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 | 設備列表對象（包括總條數、每頁條數等） |
設備列表 records 下單個對象字段說明
| 字段名稱 | 描述 |
|---|---|
| name | 設備名稱 |
| alias | 設備別名 |
| equModel | 設備物模型 |
| points | 設備的功能點列表（詳見設備點位說明） |
| devEUI | IoT 設備唯一標識 |
| location | 設備註冊位置 |
| isOnline | 設備是否在線 |
| descriptions | 設備描述 |
| isIot | 是否 IoT 設備 |
| buildingName | 設備註冊樓宇名稱 |
設備 points 單個對象字段說明
| 字段名稱 | 描述 |
|---|---|
| type | 設備點位名稱 |
| unit | 設備點位單位 |
| bmsId | 非 IoT 設備點位 ID |
| control | 是否支持反控（True 可反控，False 不可反控） |
返回錯誤碼
詳見常見請求錯誤碼
設備點位最新值查詢
提示
可查詢指定設備的點位最新值。
URL: /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 單個對象字段說明
| 字段名稱 | 描述 |
|---|---|
| time | 數據采集時間 |
| equipmentName | 設備名稱 |
| buildingName | 設備註冊樓宇信息 |
| functionType | 單個設備點位名稱 |
| devEUI | IoT 設備唯一標識 |
| value | 數字類型點位的值 |
| reading | 字符串類型點位的值 |
| unit | 設備點位單位 |
返回錯誤碼
詳見常見請求錯誤碼
設備點位歷史值查詢
提示
可查詢指定設備在某段時間內的點位歷史數據值（時間區間僅支持一週內的數據）。
URL: /device/v1/realtime/history
HTTP 請求方式: POST
身份驗證: 請求頭字段說明（加密方法詳見 API 調用 Demo）
| 字段名稱 | 字段類型 | 是否必傳 | 位置 | 描述 |
|---|---|---|---|---|
| X-Source-SecretId | string | 是 | Header | 密鑰 ID |
| X-Source-SecretKey | string | 是 | Header | 密鑰加密文本 |
請求參數
| 字段名稱 | 字段類型 | 是否必傳 | 描述 |
|---|---|---|---|
| equipmentName | string | 是 | 設備名稱（精確匹配） |
| functionType | string | 否 | 點位名稱 |
| startTime | datetime | 否 | 起始時間 |
| endTime | datetime | 否 | 結束時間 |
| 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: /dataset/v1/{datasetName}
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: /device/v1/realtime/history
HTTP請求方式: Post
身份驗證: 請求頭字段說明（加密方法詳見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 | 設備點位單位 |
返回錯誤碼
詳見請求錯誤碼