OpenAPI 指南
令牌加密传输指南
本指南旨在详细介绍如何在我们的开放平台中安全地使用RSA加密算法进行令牌（Token）的加密传输。通过遵循本指南，您将能够确保敏感数据在客户端与服务器之间的传输过程中得到最高级别的保护。
具体的操作详见
令牌加密流程
- 生成密钥对
开发者需要在中台应用中申请令牌，系统会生成密钥对，开发者下载令牌信息（信息包含密钥ID、密钥Key和公钥）,下载信息将用于加密令牌，私钥则用于解密。 - 令牌申请，下载
1、进入设备管理
进入设备管理，操作详见设备管理
2、令牌申请与下载
新增或下载令牌，操作详见令牌下载 - API接口说明
系统通过安全机制获取的令牌（Token）信息，利用RSA加密算法进行加密处理，生成加密后的密文（Ciphertext）。随后，将此密文嵌入至API（应用程序接口）请求的HTTP头部（Header）中，作为认证或授权信息的一部分，进而发起API请求。此过程确保了令牌信息在传输过程中的机密性和安全性，防止了敏感信息的泄露（加密方法可请参考下面示例代码）。
示例代码
JAVA示例文件
Golang示例文件
.Net示例文件
常见请求错误码
| 编码 | 描述 |
|---|---|
| 401 | accesstoken过期，需要重新获取 |
| 404 | 接口地址错误 |
| 428 | 用户或租户不存在 |
| 429 | 用户未注册 |
| 500 | 服务器内部错误 |
| 503 | 服务忙，稍后重试 |
| 1000 | 数据***已存在 |
设备时序数据
设备时序数据推送
tip
可接入设备上报的时序数据，一次可推送多个设备，单次请求数据总数不可超过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 |
返回错误码
详见常见请求错误码
设备详情查询
tip
可查询单个设备详情信息
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 | 单个设备对应的设备点位信息（设备points下单个对象字段说明） |
| devEUI | IoT设备唯一标识 |
| location | 设备注册位置信息 |
| isOnline | 设备是否在线（True表示在线，False表示离线） |
| descriptions | 设备描述 |
| isIot | 是否IoT设备（True是IoT设备，False非IoT设备） |
| buildingName | 设备注册楼宇名称 |
设备详情points数组单个对象字段说明
| 字段名称 | 描述 |
|---|---|
| type | 设备点位名称 |
| unit | 设备点位单位 |
| bmsId | 非IoT设备点位ID |
| control | 是否支持反控（True可反控，False不可反控） |
返回错误码
详见常见请求错误码
设备列表查询
tip
可查询当前租户下可查看的所有设备信息
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 | 设备列表对象（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不可反控） |
返回错误码
详见请求错误码
设备点位最新值查询
tip
可查询当前租户下可查看的所有设备信息
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 | 设备点位单位 |
返回错误码
详见请求错误码
设备点位历史值查询
tip
可查询某个设备下单个或所有点位的某段时间的数据值（时间区间仅可查询一周内的数据）
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 | 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 | 设备点位单位 |
返回错误码
详见请求错误码
数仓数据
数据推送
tip
可接入数据集数据（推送的字段和数据类型需和数据集配置对应），一次可推送多条（单次请求数据总数不可超过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 |
返回错误码
详见请求错误码
数据查询
tip
可查询某个设备下单个或所有点位的某段时间的数据值（时间区间仅可查询一周内的数据）
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 | 设备点位单位 |
返回错误码
详见请求错误码