API 核心功能
概述
本开放平台API提供设备时序数据与数仓数据的全链路服务，支持通过安全的RSA令牌加密机制进行身份验证。核心功能涵盖设备数据推送、详情查询、实时与历史点位数据获取，以及数据集的导入与查询，为第三方系统集成提供标准化、安全可靠的数据接口。
tip
时序数据：一系列带时间戳的数据点，用于描述设备在特定时间点的状态或测量值。它是物联网领域最常见的数据类型。
数仓数据：存储在数据仓库中的、通常经过清洗、聚合后的业务数据或主数据，可用于更复杂的分析和报表。
开始之前
权限配置
为确保以下操作流程正常进行，请您确认是否拥有项目管理员权限。
令牌加密传输指南
本指南旨在详细介绍如何在我们的开放平台中安全地使用 RSA 加密算法进行令牌（Token）的加密传输。通过遵循本指南，您将能够确保敏感数据在客户端与服务器之间的传输过程中得到最高级别的保护。
具体的操作详见下文 ->
令牌加密流程
- 生成密钥
开发者需要在中台应用中申请令牌，系统会生成密钥对，开发者下载令牌信息（信息包含密钥 ID、密钥 Key 和公钥）,下载信息将用于加密令牌，私钥则用于解密。 - 令牌申请，下载
1、进入设备管理
进入设备管理，操作详见设备管理
2、令牌申请与下载
新增或下载令牌，操作详见令牌下载 - API 接口说明
系统通过安全机制获取的令牌（Token）信息，利用 RSA 加密算法进行加密处理，生成加密后的密文（Ciphertext）。随后，将此密文嵌入至 API（应用程序接口）请求的 HTTP 头部（Header）中，作为认证或授权信息的一部分，进而发起 API 请求。此过程确保了令牌信息在传输过程中的机密性和安全性，防止了敏感信息的泄露（加密方法可请参考下面示例代码）。tip密文（Ciphertext）指的是经过加密算法处理后的、无法被直接阅读或理解的混乱数据。与之相对的是明文（Plaintext），也就是加密前的原始、可读的数据。
示例代码
Python 示例文件
JAVA 示例文件
Golang 示例文件
.Net 示例文件
Node.js 示例文件
常见请求错误码
| 编码 | 描述 |
|---|---|
| 401 | accesstoken 过期，需要重新获取 |
| 404 | 接口地址错误 |
| 428 | 用户或租户不存在 |
| 429 | 用户未注册 |
| 500 | 服务器内部错误 |
| 503 | 服务忙，稍后重试 |
| 1000 | 数据***已存在 |
设备时序数据
设备时序数据推送
tip
时序数据指一系列带时间戳的数据点，用于描述设备在特定时间点的状态或测量值。它是物联网领域最常见的数据类型。
可接入设备上报的时序数据，一次可推送多个设备，单次请求数据总数不可超过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 |
返回错误码
详见常见请求错误码
设备详情查询
tip
可查询单个设备详情信息
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 不可反控） |
返回错误码
详见常见请求错误码
设备列表查询
tip
可查询当前租户下可查看的所有设备信息
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不可反控） |
返回错误码
详见请求错误码
设备点位最新值查询
tip
可查询当前租户下可查看的所有设备信息
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 | 设备点位列表 |
返回错误码
详见请求错误码
设备点位历史值查询
tip
可查询某个设备下单个或所有点位的某段时间的数据值（时间区间仅可查询一周内的数据）
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 | 设备点位单位 |
返回错误码
详见请求错误码
数仓数据
数据推送
tip
数仓数据指存储在数据仓库中的、通常经过清洗、聚合后的业务数据或主数据，可用于更复杂的分析和报表。
可接入数据集数据（推送的字段和数据类型需和数据集配置对应），一次可推送多条（单次请求数据总数不可超过 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 |
返回错误码
详见请求错误码
数据查询
tip
可查询某个设备下单个或所有点位的某段时间的数据值（时间区间仅可查询一周内的数据）
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 | 设备点位单位 |
返回错误码
详见请求错误码