项目 HTTP API

项目 HTTP API 基于当前 OpenAPI 定义生成，用于项目级资源访问、设备管理、设备数据查询、设备控制、告警和规则查询。

准备工作

在正式调用 API 前，请在 ZhiLian.Yun 控制台的项目应用中创建 API 类型应用，获取 appId、accessKey 和 secretKey。除免登录接口外，其他接口需要在请求头中携带访问令牌。

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

平台有两类访问令牌，分别用于不同的接口分组，两者不能混用：

令牌类型	获取方式	适用接口
项目 API 访问令牌	POST /api/v1/access_token，使用应用的 appId、accessKey、secretKey 换取	设备类型、设备组、设备管理、设备扩展信息、设备数据、设备通信、设备告警、消息规则、设备上下线日志
应用管理员令牌	POST /api/v1/app-admin/login，使用项目管理员账号密码换取	应用管理员（/api/v1/app-admin/*）、当前应用与项目凭据（/api/v1/project/*）、应用用户（/api/v1/project_customers*）的写操作
无需令牌	—	服务信息、SaaS 应用公开配置（/api/v1/app-info）、应用管理员登录（/api/v1/app-admin/login）

TIP

这里的项目 API AccessToken 由 /api/v1/access_token 获取，不是设备证书中的 AccessToken，两者不能混用；也不是应用管理员登录返回的 accessToken。

WARNING

应用管理员令牌的载荷中包含 deviceType=saas 与 appId，仅能访问应用管理员相关接口；使用项目 API 访问令牌调用这些接口会返回令牌无效错误。应用用户接口中涉及写操作的部分（修改用户信息、重置用户密码、分配用户设备）还要求应用管理员账号具备对应的权限键（edit_user_info、reset_user_password、assign_user_device），权限键清单见应用管理员登录接口返回的 user.permissionKeys 与「全局定义」。

API 请求代码示例

以获取 API AccessToken 为例，项目 API 通过 HTTP JSON 请求调用。

curl -X POST "https://<endpoint>/api/v1/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "APP_ID",
    "accessKey": "ACCESS_KEY",
    "secretKey": "SECRET_KEY"
  }'

获取 API AccessToken

服务器获取 AccessToken

Request Syntax

POST /api/v1/access_token HTTP/1.1
Content-Type: application/json

Request Body

字段	类型	必填	说明
appId	string	否	应用ID
accessKey	string	否	访问KEY
secretKey	string	否	访问密钥

Request Example

{
  "appId": "APP_ID",
  "accessKey": "ACCESS_KEY",
  "secretKey": "SECRET_KEY"
}

Response Data

字段	类型	说明
accessToken	string	访问令牌
expiresIn	integer	过期时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "accessToken": "ACCESS_TOKEN",
    "expiresIn": 315360000
  },
  "error": null,
  "traceId": "TRACE_ID"
}

接口总览

方法	路径	说明	分组
POST	/api/v1/access_token	获取访问令牌	获取 API AccessToken
POST	/api/v1/device_type	新增设备类型	设备类型
DELETE	/api/v1/device_type/:typeKey	删除设备类型	设备类型
GET	/api/v1/device_type/:typeKey	获取设备类型指定信息	设备类型
GET	/api/v1/device_type/:typeKey/extend_infos	获取设备类型扩展信息列表	设备类型
PUT	/api/v1/device_type/:typeKey/info	修改设备类型信息	设备类型
GET	/api/v1/device_types	获取设备类型列表	设备类型
GET	/api/v1/device_groups_tree	读取设备组树形列表	设备组
PUT	/api/v1/device/:deviceCode/group	修改设备所属分组	设备组
POST	/api/v1/device	创建设备	设备管理
DELETE	/api/v1/device/:deviceCode	删除设备	设备管理
GET	/api/v1/device/:deviceCode	读取设备信息	设备管理
PUT	/api/v1/device/:deviceCode/info	修改设备基本信息	设备管理
GET	/api/v1/devices	读取设备列表	设备管理
GET	/api/v1/device_relations	读取网关子设备关联列表	网关子设备关联
POST	/api/v1/device_relation	添加子设备到网关	网关子设备关联
PUT	/api/v1/device_relation/:relId	修改网关子设备关联	网关子设备关联
DELETE	/api/v1/device_relation/:relId	移除网关子设备关联	网关子设备关联
POST	/api/v1/device/:deviceCode/extend_info	修改设备扩展信息	设备扩展信息
PUT	/api/v1/device/:deviceCode/extend_info	修改设备扩展信息	设备扩展信息
GET	/api/v1/device/:deviceCode/extend_infos	读取设备扩展信息	设备扩展信息
POST	/api/v1/control/device/:deviceCode/attribute_acquisition	采集设备属性	设备数据
POST	/api/v1/control/device/:deviceCode/attributes	下发设备属性	设备数据
GET	/api/v1/device/:deviceCode/attribute/:key/aggregate	获取设备历史属性聚合	设备数据
GET	/api/v1/device/:deviceCode/attribute/:key/series	获取设备历史属性	设备数据
GET	/api/v1/device/:deviceCode/attributes	获取设备最新属性	设备数据
POST	/api/v1/device/:deviceCode/attributes_remove	删除设备历史属性	设备数据
GET	/api/v1/device/:deviceCode/device_config	获取设备配置信息	设备通信
PUT	/api/v1/device/:deviceCode/device_config	修改单个设备的配置	设备通信
GET	/api/v1/device_statistic/:deviceCode	获取设备消息数	设备通信
POST	/api/v1/control/device/:deviceCode/command	发送指令	设备通信
GET	/api/v1/alarm_rule/:id	获取告警规则指定信息	设备告警
GET	/api/v1/alarm_rules	获取告警规则列表	设备告警
GET	/api/v1/alarm_log/:id/info	获取告警历史指定信息	设备告警
PUT	/api/v1/alarm_log/:id/maintain_info	修改告警历史维护信息	设备告警
GET	/api/v1/alarm_logs	读取所有告警消息	设备告警
GET	/api/v1/rules	获取规则列表	消息规则
GET	/api/v1/rules/:id	获取规则指定信息	消息规则
GET	/api/v1/device/:deviceCode/online_logs	获取设备上下线日志列表	设备上下线日志
POST	/api/v1/app-admin/login	应用管理员登录	应用管理员
GET	/api/v1/app-admin/me	获取当前应用管理员	应用管理员
POST	/api/v1/app-admin/refresh	刷新应用管理员令牌	应用管理员
POST	/api/v1/app-admin/logout	应用管理员退出登录	应用管理员
GET	/api/v1/app-admin/boards	获取应用允许访问的看板	应用管理员
GET	/api/v1/app-admin/boards/:boardId	获取应用看板	应用管理员
GET	/api/v1/app-admin/boards/:boardId/data	获取应用看板数据	应用管理员
GET	/api/v1/app-info	根据应用ID获取SaaS应用公开配置	SaaS 应用
GET	/api/v1/project/current	获取当前应用项目	SaaS 应用
GET	/api/v1/project/mqtt-credentials	获取当前项目MQTT凭据	SaaS 应用
GET	/api/v1/project_customers	获取应用用户列表	应用用户
GET	/api/v1/project_customers/:id	获取应用用户详情	应用用户
PUT	/api/v1/project_customers/:id	修改应用用户信息	应用用户
PUT	/api/v1/project_customers/:id/password	重置应用用户密码	应用用户
GET	/api/v1/project_customers/:id/devices	获取用户关联设备	应用用户
POST	/api/v1/project_customers/:id/devices	添加用户关联设备	应用用户
DELETE	/api/v1/project_customers/:id/devices	移除用户关联设备	应用用户
GET	/api/v1/info	服务信息	服务信息

设备类型

获取设备类型列表

Request Syntax

GET /api/v1/device_types HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	ID
name	string	否	类型名称
createdAt	array<string>	否	创建时间
typeKey	string	否	类型KEY
connType	integer	否	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	否	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
productKey	string	否	产品识别码
scanTypeKey	string	否	扫描类型KEY,结合Sort使用
sort	string	否	排序方式(type_key_asc:类型KEY升序，type_key_desc:类型KEY降序)
typeKeys	array<string>	否	类型KEY列表

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjDeviceTypesListModel>	数据列表
items[].id	integer	ID
items[].name	string	类型名称
items[].descr	string	类型描述
items[].icon	string	类型图标
items[].connProtocol	integer	设备通信方式：1 WiFi，2 以太网，3 4G，4 5G，5 NB-IoT，6 RS485，7 RS232，8 RS422，9 LoRa，10 Zigbee，11 BLE，99 其他。
items[].connType	integer	设备接入类型：1 直连设备，2 子设备，3 网关设备。
items[].msgProtocol	integer	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
items[].onlineDelay	integer	在线超时时间(秒)
items[].activeDelay	integer	活跃超时时间(秒)
items[].typeKey	string	类型KEY
items[].productKey	string	产品识别码
items[].openRule	integer	是否启用规则：0 未开启，1 已开启。
items[].createdAt	string	创建时间
items[].deviceCount	integer	设备数量

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "名称",
        "descr": "描述",
        "icon": "string",
        "connProtocol": 1
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备类型信息

Request Syntax

GET /api/v1/device_type/:typeKey HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
typeKey	string	是	类型KEY

Query Parameters

参数	类型	必填	说明
id	integer	否	ID

Response Data

字段	类型	说明
id	integer	ID
name	string	类型名称
descr	string	类型描述
icon	string	类型图标
connProtocol	integer	设备通信方式：1 WiFi，2 以太网，3 4G，4 5G，5 NB-IoT，6 RS485，7 RS232，8 RS422，9 LoRa，10 Zigbee，11 BLE，99 其他。
connType	integer	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
onlineDelay	integer	在线超时时间(秒)
activeDelay	integer	活跃超时时间(秒)
masterModel	string	主模型
pluginModel	string	插件模型
typeKey	string	类型KEY
openAutoCreate	integer	是否允许设备自动创建：0 未开启，1 已开启。
openCreateList	integer	是否启用设备白名单：0 未开启，1 已开启。
createListApi	string	设备白名单验证API
openProductKey	integer	是否启用产品识别码：0 未开启，1 已开启。
productKey	string	产品识别码
openProductConfig	integer	是否启用产品默认配置：0 未开启，1 已开启。
productConfig	string	产品默认配置
openRule	integer	是否启用规则：0 未开启，1 已开启。
updateVer	integer	更新版本
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
deviceCount	integer	设备数量
panelConfig	string	面板配置
userConfig	string	用户配置
createDefaultStream	boolean	已创建默认自定义数据流。
defaultStreamDataType	string	默认自定义数据流消息格式。
defaultStreamTcpEnabled	boolean	默认自定义数据流是否支持 TCP 接入。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称",
    "descr": "描述",
    "icon": "string",
    "connProtocol": 1,
    "connType": 1,
    "msgProtocol": 1,
    "onlineDelay": 1,
    "activeDelay": 1,
    "masterModel": "string",
    "pluginModel": "string",
    "typeKey": "TYPE_KEY"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备类型扩展信息定义

Request Syntax

GET /api/v1/device_type/:typeKey/extend_infos HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
typeKey	string	是	设备类型KEY

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjDevTypeExtendListModel>	数据列表
items[].id	integer	ID
items[].typeKey	string	设备类型KEY
items[].name	string	名称
items[].descr	string	描述
items[].infoType	string	扩展类型。内置值：location 地理坐标。
items[].infoConfig	string	配置
items[].enabled	integer	是否启用：0 未启用，1 已启用。
items[].createdAt	string	创建时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "typeKey": "TYPE_KEY",
        "name": "名称",
        "descr": "描述",
        "infoType": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

创建设备类型

Request Syntax

POST /api/v1/device_type HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Request Body

字段	类型	必填	说明
id	integer	否	ID
name	string	否	类型名称
descr	string	否	类型描述
icon	string	否	类型图标
connProtocol	integer	否	设备通信方式：1 WiFi，2 以太网，3 4G，4 5G，5 NB-IoT，6 RS485，7 RS232，8 RS422，9 LoRa，10 Zigbee，11 BLE，99 其他。
connType	integer	否	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	否	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
onlineDelay	integer	否	在线超时时间(秒)
activeDelay	integer	否	活跃超时时间(秒)
masterModel	string	否	主模型
plugin_model	string	否	插件模型
openAutoCreate	integer	否	是否允许设备自动创建：0 未开启，1 已开启。
openCreateList	integer	否	是否启用设备白名单：0 未开启，1 已开启。
createListApi	string	否	设备白名单验证API
openProductKey	integer	否	是否启用产品识别码：0 未开启，1 已开启。
productKey	string	否	产品识别码
openProductConfig	integer	否	是否启用产品默认配置：0 未开启，1 已开启。
productConfig	string	否	产品默认配置
openRule	integer	否	是否启用规则：0 未开启，1 已开启。
createDefaultStream	boolean	否	是否同时创建默认自定义数据流。
defaultStreamDataType	string	否	默认自定义数据流消息格式（JSON / HEX / Plaintext）。
defaultStreamTcpEnabled	boolean	否	默认自定义数据流是否支持 TCP 接入。

Request Example

{
  "id": 1,
  "name": "名称",
  "descr": "描述",
  "icon": "string",
  "connProtocol": 1,
  "connType": 1,
  "msgProtocol": 1,
  "onlineDelay": 1,
  "activeDelay": 1,
  "masterModel": "string",
  "plugin_model": "string",
  "openAutoCreate": 1
}

Response Data

字段	类型	说明
id	integer	设备类型ID
typeKey	string	设备类型KEY

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "typeKey": "TYPE_KEY"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备类型信息

Request Syntax

PUT /api/v1/device_type/:typeKey/info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
typeKey	string	是	路径参数

Request Body

字段	类型	必填	说明
id	integer	否	ID
name	string	否	类型名称
descr	string	否	类型描述
icon	string	否	类型图标
connProtocol	integer	否	设备通信方式：1 WiFi，2 以太网，3 4G，4 5G，5 NB-IoT，6 RS485，7 RS232，8 RS422，9 LoRa，10 Zigbee，11 BLE，99 其他。
connType	integer	否	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	否	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
onlineDelay	integer	否	在线超时时间(秒)
activeDelay	integer	否	活跃超时时间(秒)
masterModel	string	否	主模型
plugin_model	string	否	插件模型
openAutoCreate	integer	否	是否允许设备自动创建：0 未开启，1 已开启。
openCreateList	integer	否	是否启用设备白名单：0 未开启，1 已开启。
createListApi	string	否	设备白名单验证API
openProductKey	integer	否	是否启用产品识别码：0 未开启，1 已开启。
productKey	string	否	产品识别码
openProductConfig	integer	否	是否启用产品默认配置：0 未开启，1 已开启。
productConfig	string	否	产品默认配置
openRule	integer	否	是否启用规则：0 未开启，1 已开启。
createDefaultStream	boolean	否	是否同时创建默认自定义数据流。
defaultStreamDataType	string	否	默认自定义数据流消息格式（JSON / HEX / Plaintext）。
defaultStreamTcpEnabled	boolean	否	默认自定义数据流是否支持 TCP 接入。

Request Example

{
  "id": 1,
  "name": "名称",
  "descr": "描述",
  "icon": "string",
  "connProtocol": 1,
  "connType": 1,
  "msgProtocol": 1,
  "onlineDelay": 1,
  "activeDelay": 1,
  "masterModel": "string",
  "plugin_model": "string",
  "openAutoCreate": 1
}

Response Data

字段	类型	说明
id	integer	设备类型ID
typeKey	string	设备类型KEY

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "typeKey": "TYPE_KEY"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

删除设备类型

Request Syntax

DELETE /api/v1/device_type/:typeKey HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
typeKey	string	是	路径参数

Query Parameters

参数	类型	必填	说明
id	interface	否	ID

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

设备组

读取设备组树形列表

Request Syntax

GET /api/v1/device_groups_tree HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
items	array<internal.model.XjGroupsTreeModel>	数据列表
items[].id	integer	ID
items[].name	string	名称
items[].groupKey	string	分组KEY
items[].descr	string	描述
items[].parentKey	string	父分组KEY
items[].createdAt	string	创建时间
items[].deviceCount	integer	设备数量
items[].childCount	integer	子分组数量
items[].children	array<internal.model.XjGroupsTreeModel>	子分组

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "名称",
        "groupKey": "string",
        "descr": "描述",
        "parentKey": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备所属分组

Request Syntax

PUT /api/v1/device/:deviceCode/group HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Request Body

字段	类型	必填	说明
groupKey	string	否	分组KEY，为空表示移出分组

Request Example

{
  "groupKey": "GROUP_KEY"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

设备管理

读取设备列表

Request Syntax

GET /api/v1/devices HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	设备ID
name	string	否	设备名称
deviceCode	string	否	设备码
status	string	否	设备启用状态：0 启用，1 禁用。
typeKey	string	否	设备类型
onlineStatus	integer	否	设备在线状态：1 在线，2 离线。
activeStatus	integer	否	设备列表活跃状态：1 活跃，2 5 分钟内活跃，3 1 小时内活跃，4 1 天内活跃，20 不活跃，21 不活跃超过 1 天，22 不活跃超过 3 天，23 不活跃超过 7 天，30 从未活跃。
debugStatus	integer	否	设备调试状态：0 未开启，1 已开启。
createdAt	array<string>	否	创建时间
alarmStatus	integer	否	设备告警状态：1 未告警，2 告警中，3 普通告警，4 重要告警，5 紧急告警。
connType	integer	否	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	否	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
connTypes	string	否	设备接入类型列表，逗号分隔（如 2,3）。级联场景下网关下既可挂子设备也可挂网关设备，需要一次筛多个类型；与 connType 同时传入时以本参数为准。
groupNotIn	string	否	设备不在那个分组下(用于设备组筛选)
groupKey	string	否	设备分组KEY
sort	string	否	排序方式(last_active_desc:最后活跃,created_asc:最早创建时间,created_desc:最新创建时间,name_asc:名称升序，device_code_asc:设备码升序，device_code_desc:设备码降序)
isNoFatherDevice	boolean	否	只查未挂到任何网关下的设备。筛选类型含子设备或网关设备时生效（网关设备挂在网关下即为级联）。
scanDeviceCode	string	否	扫描设备码,结合Sort使用
deviceCodes	array<string>	否	设备码列表

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjDevicesListModel>	数据列表
items[].id	integer	设备ID
items[].name	string	设备名称
items[].descr	string	设备描述
items[].typeKey	string	设备类型KEY
items[].typeIcon	string	设备类型图标
items[].deviceKey	string	设备唯一标识(嵌入式端)
items[].deviceCode	string	设备码
items[].status	string	设备启用状态：0 启用，1 禁用。
items[].onlineStatus	integer	设备在线状态：1 在线，2 离线。
items[].activeStatus	integer	设备列表活跃状态：1 活跃，2 5 分钟内活跃，3 1 小时内活跃，4 1 天内活跃，20 不活跃，21 不活跃超过 1 天，22 不活跃超过 3 天，23 不活跃超过 7 天，30 从未活跃。
items[].debugStatus	integer	设备调试状态：0 未开启，1 已开启。
items[].debugEnableTime	integer	设备调试时间
items[].lat	number	设备坐标纬度
items[].lng	number	设备坐标经度
items[].alarmStatus	integer	设备告警状态：1 未告警，2 告警中，3 普通告警，4 重要告警，5 紧急告警。
items[].firstLoginAt	integer	第一次登录时间戳(毫秒)
items[].lastLoginAt	integer	最后登录时间戳(毫秒)
items[].lastActiveAt	integer	最后活跃时间戳(毫秒)
items[].typeName	string	设备类型名称
items[].typeOpenRule	integer	设备类型启用规则：0 未开启，1 已开启。
items[].group	object<string, string>	设备分组
items[].otaModule	string	OTA模块
items[].otaVersion	string	OTA版本
items[].otaModule2	string	OTA模块2
items[].otaVersion2	string	OTA版本2
items[].otaModule3	string	OTA模块3
items[].otaVersion3	string	OTA版本3
items[].otaModule4	string	OTA模块4
items[].otaVersion4	string	OTA版本4
items[].connType	integer	设备接入类型：1 直连设备，2 子设备，3 网关设备。
items[].msgProtocol	integer	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
items[].onlineDelay	integer	在线超时时间(秒)
items[].activeDelay	integer	活跃超时时间(秒)
items[].updateVer	integer	更新版本
items[].iccid	string	ICCID(冗余)
items[].signalQuality	integer	信号强度：0-4，数值越大通常表示信号越好。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "名称",
        "descr": "描述",
        "typeKey": "TYPE_KEY",
        "deviceKey": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备信息

Request Syntax

GET /api/v1/device/:deviceCode HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Query Parameters

参数	类型	必填	说明
id	integer	否	设备ID

Response Data

字段	类型	说明
id	integer	设备ID
name	string	设备名称
descr	string	设备描述
typeKey	string	设备类型KEY
deviceKey	string	设备唯一标识(嵌入式端)
deviceCode	string	设备码
status	string	设备启用状态：0 启用，1 禁用。
onlineStatus	integer	设备在线状态：1 在线，2 离线。
alarmStatus	integer	设备告警状态：1 未告警，2 告警中，3 普通告警，4 重要告警，5 紧急告警。
debugStatus	integer	设备调试状态：0 未开启，1 已开启。
debugEnableTime	integer	设备调试时间戳(毫秒)
gatewayDeviceCode	string	网关设备码
subDeviceAddr	string	子设备地址
gatewayAddTime	string	网关添加时间
address	string	设备位置
lat	number	设备坐标纬度
lng	number	设备坐标经度
regionCode	string	行政区域代码
locationBuilding	string	建筑
locationUnit	string	单元
locationFloor	string	楼层
locationRoom	string	房号
deviceSecret	string	设备密钥
firstLoginAt	integer	第一次登录时间戳(毫秒)
lastLoginAt	integer	最后登录时间戳(毫秒)
lastActiveAt	integer	最后活跃时间戳(毫秒)
otaLock	integer	OTA 升级锁定状态：0 未锁定，1 已锁定。
otaModule	string	OTA模块
otaVersion	string	OTA版本
otaModule2	string	OTA模块2
otaVersion2	string	OTA版本2
otaModule3	string	OTA模块3
otaVersion3	string	OTA版本3
otaModule4	string	OTA模块4
otaVersion4	string	OTA版本4
connType	integer	设备接入类型：1 直连设备，2 子设备，3 网关设备。
msgProtocol	integer	设备接入协议：1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他。
onlineDelay	integer	在线超时时间(秒)
activeDelay	integer	活跃超时时间(秒)
updateVer	integer	更新版本
iccid	string	ICCID(冗余)
signalQuality	integer	信号强度：0-4，数值越大通常表示信号越好。
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
typeName	string	设备类型名称
typeOpenRule	integer	设备类型启用规则：0 未开启，1 已开启。
masterModel	string	物模型
connInfo	internal.model.XjDeviceConnInfo	设备连接信息
connInfo.deviceCode	string	设备码
connInfo.loginTimeMs	integer	最后登录时间(毫秒)
connInfo.lastTimeMs	integer	最后在线时间(毫秒)
connInfo.onlineDelay	integer	在线超时时间(秒)
connInfo.activeDelay	integer	活跃超时时间(秒)
connInfo.svrType	integer	数据服务类型
connInfo.svrCode	string	数据服务编号
connInfo.connId	integer	连接ID
connInfo.connStatus	integer	连接状态(0:离线 1:在线)
connInfo.gatewayCode	string	网关设备码
connInfo.subAddrAll	string	子设备地址全路径
connInfo.msgTypeTime	object<string, integer>	消息类型时间(毫秒)
connInfo.isOnline	boolean	设备在线状态：1 在线，2 离线。
group	array<internal.model.Group>	设备分组
group[].router	string
group[].key	string
group[].id	integer
parentDeviceId	integer	网关设备ID
parentDeviceName	string	网关设备名称
safeDeviceCode	string	安全设备码（设备码 + 2 位校验码），控制台按"设备码类型=安全设备码"展示。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称",
    "descr": "描述",
    "typeKey": "TYPE_KEY",
    "deviceKey": "string",
    "deviceCode": "DEVICE_CODE",
    "status": "string",
    "onlineStatus": 1,
    "alarmStatus": 1,
    "debugStatus": 1,
    "debugEnableTime": 1626197189,
    "gatewayDeviceCode": "DEVICE_CODE"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

创建设备

Request Syntax

POST /api/v1/device HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Request Body

字段	类型	必填	说明
id	integer	否	设备ID
name	string	否	设备名称
descr	string	否	设备描述
typeKey	string	否	设备类型KEY
deviceKey	string	否	设备唯一标识(嵌入式端)
status	string	否	设备启用状态：0 启用，1 禁用。
debugStatus	integer	否	设备调试状态：0 未开启，1 已开启。
debugEnableTime	integer	否	设备调试时间
firstLoginAt	integer	否	第一次登录时间戳（毫秒），即设备激活时间。
otaLock	integer	否	升级锁定：0 未锁定，1 已锁定。
address	string	否	设备位置
lat	number	否	设备坐标纬度
lng	number	否	设备坐标经度
regionCode	string	否	行政区域代码
locationBuilding	string	否	建筑
locationUnit	string	否	单元
locationFloor	string	否	楼层
locationRoom	string	否	房号

Request Example

{
  "id": 1,
  "name": "名称",
  "descr": "描述",
  "typeKey": "TYPE_KEY",
  "deviceKey": "string",
  "status": "string",
  "debugStatus": 1,
  "debugEnableTime": 1626197189,
  "address": "string",
  "lat": 1.23,
  "lng": 1.23,
  "regionCode": "string"
}

Response Data

字段	类型	说明
id	integer	设备ID
deviceCode	string	设备码

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "deviceCode": "DEVICE_CODE"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备基本信息

Request Syntax

PUT /api/v1/device/:deviceCode/info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
id	integer	否	设备ID
name	string	否	设备名称
descr	string	否	设备描述
typeKey	string	否	设备类型KEY
deviceKey	string	否	设备唯一标识(嵌入式端)
status	string	否	设备启用状态：0 启用，1 禁用。
debugStatus	integer	否	设备调试状态：0 未开启，1 已开启。
debugEnableTime	integer	否	设备调试时间
firstLoginAt	integer	否	第一次登录时间戳（毫秒），即设备激活时间。
otaLock	integer	否	升级锁定：0 未锁定，1 已锁定。
address	string	否	设备位置
lat	number	否	设备坐标纬度
lng	number	否	设备坐标经度
regionCode	string	否	行政区域代码
locationBuilding	string	否	建筑
locationUnit	string	否	单元
locationFloor	string	否	楼层
locationRoom	string	否	房号

Request Example

{
  "id": 1,
  "name": "名称",
  "descr": "描述",
  "typeKey": "TYPE_KEY",
  "deviceKey": "string",
  "status": "string",
  "debugStatus": 1,
  "debugEnableTime": 1626197189,
  "address": "string",
  "lat": 1.23,
  "lng": 1.23,
  "regionCode": "string"
}

Response Data

字段	类型	说明
id	integer	设备ID
deviceCode	string	设备码

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "deviceCode": "DEVICE_CODE"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

移除设备

Request Syntax

DELETE /api/v1/device/:deviceCode HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Query Parameters

参数	类型	必填	说明
id	interface	否	设备ID

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

网关子设备关联

管理网关与子设备的绑定关系，可用于搭建多级网关（网关下再挂网关，子设备地址用 . 分隔层级，详见网关 MQTT 接入的多级网关说明）。

绑定约束：

• 父设备必须是网关设备（connType=3），被绑定的设备可以是子设备或网关设备（级联）。
• 父子设备的接入协议（msgProtocol）必须一致。
• 子设备地址在同一网关下唯一，不能包含 .（. 是层级分隔符）。
• 不能把设备关联到它自己的下级（防环）。

读取网关子设备关联列表

Request Syntax

GET /api/v1/device_relations?parentDeviceCode=GATEWAY_DEVICE_CODE HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Request Parameters

参数	类型	必填	说明
parentDeviceCode	string	否	网关设备码，传则只返回该网关下的关联
relId	integer	否	关联ID
keyword	string	否	关键字
createdAt	array<string>	否	创建时间
page	integer	否	页码，默认 1
pageSize	integer	否	每页数量，默认 20

Response Data

字段	类型	说明
page	integer	当前页码
total	integer	数据总数
items	array<object>	数据列表
items[].relId	integer	关联ID
items[].parentDeviceCode	string	网关设备码
items[].subDeviceCode	string	子设备码
items[].subDeviceAddr	string	子设备地址
items[].subDeviceId	integer	子设备ID
items[].name	string	子设备名称
items[].onlineStatus	integer	子设备在线状态：1 在线，2 离线。
items[].lastActiveAt	integer	最后活跃时间戳（毫秒）
items[].alarmStatus	integer	子设备告警状态：1 未告警，2 告警中，3 普通告警，4 重要告警，5 紧急告警。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "total": 1,
    "items": [
      {
        "relId": 1,
        "parentDeviceCode": "GATEWAY_DEVICE_CODE",
        "subDeviceCode": "SUB_DEVICE_CODE",
        "subDeviceAddr": "1",
        "subDeviceId": 1,
        "name": "子设备名称",
        "onlineStatus": 1,
        "lastActiveAt": 1626197189640,
        "alarmStatus": 1
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

添加子设备到网关

Request Syntax

POST /api/v1/device_relation HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Request Body

字段	类型	必填	说明
parentDeviceCode	string	是	网关设备码
subDeviceCode	array<string>	是	子设备码列表，可一次绑定多个

Request Example

{
  "parentDeviceCode": "GATEWAY_DEVICE_CODE",
  "subDeviceCode": ["SUB_DEVICE_CODE1", "SUB_DEVICE_CODE2"]
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

TIP

新绑定的子设备初始没有子设备地址。网关上报 gateway/connect 前必须先设置地址， 否则平台无法把报文归属到子设备。用下面的「修改网关子设备关联」接口设置。

修改网关子设备关联

当前仅支持修改子设备地址。

Request Syntax

PUT /api/v1/device_relation/:relId HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
relId	integer	是	关联ID，从列表接口获得

Request Body

字段	类型	必填	说明
subDeviceAddr	string	是	子设备地址，不能包含 .

Request Example

{
  "subDeviceAddr": "1"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

移除网关子设备关联

解除子设备与网关的绑定，子设备的网关设备码与子设备地址会被清空。

Request Syntax

DELETE /api/v1/device_relation/:relId HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
relId	integer	是	关联ID

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

设备扩展信息

读取设备扩展信息

Request Syntax

GET /api/v1/device/:deviceCode/extend_infos HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjDeviceExtendsListModel>	数据列表
items[].id	integer	ID
items[].deviceCode	string	设备码
items[].name	string	名称
items[].typeExtendId	integer	扩展类型。内置值：location 地理坐标。ID
items[].infoType	string	扩展类型。内置值：location 地理坐标。
items[].extendValue	string	扩展数据值
items[].createdDept	integer	创建部门
items[].createdBy	integer	创建者
items[].createdBySumma	internal.library.xgorm.hook.MemberSumma	创建者摘要信息
items[].createdAt	string	创建时间
items[].updatedBy	integer	更新者
items[].updatedBySumma	internal.library.xgorm.hook.MemberSumma	更新者摘要信息
items[].updatedAt	string	更新时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "deviceCode": "DEVICE_CODE",
        "name": "名称",
        "typeExtendId": 1,
        "infoType": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备扩展信息（POST）

Request Syntax

POST /api/v1/device/:deviceCode/extend_info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
id	integer	否	ID
deviceCode	string	否	设备码
name	string	否	名称
typeExtendId	integer	否	扩展类型。内置值：location 地理坐标。ID
infoType	string	扩展类型。内置值：location 地理坐标。	扩展类型。内置值：location 地理坐标。
extendValue	string	否	扩展数据值
tenantId	string	否	租户ID
createdDept	integer	否	创建部门
createdBy	integer	否	创建者
createdAt	string	否	创建时间
updatedBy	integer	否	更新者
updatedAt	string	否	更新时间

Request Example

{
  "id": 1,
  "deviceCode": "DEVICE_CODE",
  "name": "名称",
  "typeExtendId": 1,
  "infoType": "string",
  "extendValue": "string",
  "tenantId": "string",
  "createdDept": 1,
  "createdBy": 1,
  "createdAt": "string",
  "updatedBy": 1,
  "updatedAt": "string"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备扩展信息（PUT）

Request Syntax

PUT /api/v1/device/:deviceCode/extend_info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
id	integer	否	ID
deviceCode	string	否	设备码
name	string	否	名称
typeExtendId	integer	否	扩展类型。内置值：location 地理坐标。ID
infoType	string	扩展类型。内置值：location 地理坐标。	扩展类型。内置值：location 地理坐标。
extendValue	string	否	扩展数据值
tenantId	string	否	租户ID
createdDept	integer	否	创建部门
createdBy	integer	否	创建者
createdAt	string	否	创建时间
updatedBy	integer	否	更新者
updatedAt	string	否	更新时间

Request Example

{
  "id": 1,
  "deviceCode": "DEVICE_CODE",
  "name": "名称",
  "typeExtendId": 1,
  "infoType": "string",
  "extendValue": "string",
  "tenantId": "string",
  "createdDept": 1,
  "createdBy": 1,
  "createdAt": "string",
  "updatedBy": 1,
  "updatedAt": "string"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

设备数据

读取设备当前属性值集合

Request Syntax

GET /api/v1/device/:deviceCode/attributes HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Response Data

字段	类型	说明
deviceCode	string	设备码
list	array<git.xiujie.cn.cloud.cloud-public.xjpubmodel.XjDeviceProperty>	属性列表
list[].key	string	属性标识
list[].name	string	属性名称(可空)
list[].type	string	属性值类型(可空)
list[].unit	string	属性值单位(可空)
list[].v	github.com.gogf.gf.v2.container.gvar.Var	属性值
list[].ts	string	时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "deviceCode": "DEVICE_CODE",
    "list": [
      {
        "key": "temperature",
        "name": "名称",
        "type": "string",
        "unit": "string",
        "v": {}
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备属性历史数据

Request Syntax

GET /api/v1/device/:deviceCode/attribute/:key/series HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备SN
key	string	是	属性标识

Query Parameters

参数	类型	必填	说明
version	integer	否	物模型版本：0 表示最新版本。
startTime	string	否	开始时间
endTime	string	否	结束时间
isAsc	boolean	否	是否升序
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
data	array<git.xiujie.cn.cloud.cloud-public.xjpubmodel.XjDeviceProperty>
data[].key	string	属性标识
data[].name	string	属性名称(可空)
data[].type	string	属性值类型(可空)
data[].unit	string	属性值单位(可空)
data[].v	github.com.gogf.gf.v2.container.gvar.Var	属性值
data[].ts	string	时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "data": [
      {
        "key": "temperature",
        "name": "名称",
        "type": "string",
        "unit": "string",
        "v": {}
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备属性聚合统计数据

Request Syntax

GET /api/v1/device/:deviceCode/attribute/:key/aggregate HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备SN
key	string	是	属性标识

Query Parameters

参数	类型	必填	说明
version	integer	否	物模型版本：0 表示最新版本。
startTime	string	否	开始时间
endTime	string	否	结束时间
isAsc	boolean	否	是否升序
aggregateWindow	string	否	聚合窗口
aggregateFunction	string	否	聚合函数
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
data	array<git.xiujie.cn.cloud.cloud-public.xjpubmodel.XjDeviceProperty>
data[].key	string	属性标识
data[].name	string	属性名称(可空)
data[].type	string	属性值类型(可空)
data[].unit	string	属性值单位(可空)
data[].v	github.com.gogf.gf.v2.container.gvar.Var	属性值
data[].ts	string	时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "data": [
      {
        "key": "temperature",
        "name": "名称",
        "type": "string",
        "unit": "string",
        "v": {}
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

移除设备属性

Request Syntax

POST /api/v1/device/:deviceCode/attributes_remove HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
deviceCode	string	否	设备SN
keys	array<string>	否	属性标识列表,必填
isRemove	boolean	否	是否移除属性,true:移除最后属性和历史属性,false:保留最后属性
startTime	string	否	开始时间,可空
endTime	string	否	结束时间,可空

Request Example

{
  "deviceCode": "DEVICE_CODE",
  "keys": [
    "string"
  ],
  "isRemove": true,
  "startTime": "string",
  "endTime": "string"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

采集设备属性

Request Syntax

POST /api/v1/control/device/:deviceCode/attribute_acquisition HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
deviceCode	string	否	设备SN,必填
keys	array<string>	否	属性标识列表,可空
isAsync	boolean	否	是否异步调用,同步:false,异步:true 同步调用等待设备响应
syncTimeout	integer	否	同步超时时间秒,默认10秒

Request Example

{
  "deviceCode": "DEVICE_CODE",
  "keys": [
    "string"
  ],
  "isAsync": true,
  "syncTimeout": 1626197189
}

Response Data

字段	类型	说明
deviceCode	string	设备SN,必填
code	integer	返回码
message	string	返回消息
output	object<string, interface>	输出参数
outData	string	输出数据原始设备数据,可空
inData	string	输入数据原始设备数据,可空

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "deviceCode": "DEVICE_CODE",
    "code": 1,
    "message": "string",
    "output": {
      "key": {}
    },
    "outData": "string",
    "inData": "string"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

下发设备属性

Request Syntax

POST /api/v1/control/device/:deviceCode/attributes HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
msgId	integer	否	消息ID,可空
deviceCode	string	否	设备SN,必填
input	object<string, interface>	否	输入参数
isAsync	boolean	否	是否异步调用,同步:false,异步:true 同步调用等待设备响应
syncTimeout	integer	否	同步超时时间秒,默认10秒

Request Example

{
  "msgId": 1,
  "deviceCode": "DEVICE_CODE",
  "input": {
    "key": {}
  },
  "isAsync": true,
  "syncTimeout": 1626197189
}

Response Data

字段	类型	说明
msgId	integer	消息ID,可空
deviceCode	string	设备SN,必填
code	integer	返回码
message	string	返回消息
outData	string	输出数据原始设备数据,可空
inData	string	输入数据原始设备数据,可空

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "msgId": 1,
    "deviceCode": "DEVICE_CODE",
    "code": 1,
    "message": "string",
    "outData": "string",
    "inData": "string"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

设备通信

下发命令到设备

Request Syntax

POST /api/v1/control/device/:deviceCode/command HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
msgId	integer	否	消息ID,可空
deviceCode	string	否	设备SN,必填
key	string	否	指令标识,必填
input	object<string, interface>	否	输入参数
isAsync	boolean	否	是否异步调用,同步:false,异步:true 同步调用等待设备响应
syncTimeout	integer	否	同步超时时间秒,默认10秒

Request Example

{
  "msgId": 1,
  "deviceCode": "DEVICE_CODE",
  "key": "temperature",
  "input": {
    "key": {}
  },
  "isAsync": true,
  "syncTimeout": 1626197189
}

Response Data

字段	类型	说明
msgId	integer	消息ID,可空
deviceCode	string	设备SN,必填
key	string	指令标识,必填
code	integer	返回码
message	string	返回消息
output	object<string, interface>	输出参数
outData	string	输出数据原始设备数据,可空
inData	string	输入数据原始设备数据,可空

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "msgId": 1,
    "deviceCode": "DEVICE_CODE",
    "key": "temperature",
    "code": 1,
    "message": "string",
    "output": {
      "key": {}
    },
    "outData": "string",
    "inData": "string"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备配置信息

Request Syntax

GET /api/v1/device/:deviceCode/device_config HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Response Data

字段	类型	说明
id	integer	ID
deviceCode	string	设备码
confGroupKey	string	配置分组Key
deviceConfId	integer	设备内配置ID
deviceConfVer	integer	设备内配置版本
platDevConfVer	integer	平台配置设备版本号（无分组）
platDevConfId	integer	平台配置版本ID（无分组）
platGroupConfVer	integer	平台分组配置版本号（有分组）
platGroupConfId	integer	平台分组配置版本ID（有分组）
deviceConfAt	string	设备端版本更新时间
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
deviceConfigContent	string	设备配置内容
groupConfigContent	string	分组配置内容

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "deviceCode": "DEVICE_CODE",
    "confGroupKey": "string",
    "deviceConfId": 1,
    "deviceConfVer": 1,
    "platDevConfVer": 1,
    "platDevConfId": 1,
    "platGroupConfVer": 1,
    "platGroupConfId": 1,
    "deviceConfAt": "string",
    "tenantId": "string",
    "createdDept": 1
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改设备配置

Request Syntax

PUT /api/v1/device/:deviceCode/device_config HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	路径参数

Request Body

字段	类型	必填	说明
deviceCode	string	否	设备码
configContent	string	否	配置内容（分组配置、设备配置）
fileUrl	string	否	文件地址
filePath	string	否	文件本地路径
fileMd5	string	否	文件md5

Request Example

{
  "deviceCode": "DEVICE_CODE",
  "configContent": "string",
  "fileUrl": "string",
  "filePath": "string",
  "fileMd5": "string"
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

读取设备消息统计

Request Syntax

GET /api/v1/device_statistic/:deviceCode HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Query Parameters

参数	类型	必填	说明
time	string	是	统计时间范围，可选值：24h、3d、7d、15d、30d。不传会返回时间参数错误。

Response Data

字段	类型	说明
times	array<string>
series	array<internal.model.MsgSeries>
series[].type	integer
series[].name	string
series[].data	array<integer>
total	array<integer>

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "times": [
      "string"
    ],
    "series": [
      {
        "type": 1,
        "name": "名称",
        "data": [
          "integer"
        ]
      }
    ],
    "total": [
      1
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

设备告警

读取所有告警消息

Request Syntax

GET /api/v1/alarm_logs HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	日志ID
alarmStatus	integer	否	告警状态：0 正常，1 告警中，2 待定。
alarmLevel	integer	否	告警级别：1 普通告警，2 重要告警，3 紧急告警。
createdAt	array<string>	否	创建时间
deviceCode	string	否	设备码
dsType	string	否	设备来源类型：device_type 设备类型，device 设备。
dsSource	string	否	来源标识
alarmRuleId	integer	否	告警规则ID
alarmRuleName	string	否	告警规则名称
scanId	integer	否	扫描ID,结合Sort使用
sort	string	否	排序方式(id_asc:ID升序，id_desc:ID降序)

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjAlarmLogsListModel>	数据列表
items[].id	integer	日志ID
items[].alarmRuleId	integer	告警规则ID
items[].alarmRuleName	string	告警规则名称
items[].alarmRuleDescr	string	告警规则描述
items[].deviceCode	string	设备码
items[].deviceName	string	设备名称
items[].alarmLevel	integer	告警级别：1 普通告警，2 重要告警，3 紧急告警。
items[].alarmStatus	integer	告警状态：0 正常，1 告警中，2 待定。
items[].alarmInfo	string	告警信息
items[].triggerInfo	string	触发信息
items[].snapshot	string	设备快照
items[].maintainInfo	string	维护信息
items[].maintainTs	integer	维护更新时间戳秒
items[].maintainer	string	维护信息更新用户
items[].recoverAlarmType	integer	恢复告警类型
items[].recoverAlarmAt	string	恢复告警时间
items[].recoverAlarmRuleId	integer	恢复告警规则ID
items[].recoverAlarmRuleName	string	恢复告警规则名称
items[].recoverTriggerInfo	string	恢复时触发信息
items[].recoverUserType	integer	恢复告警用户类型
items[].recoverUserId	integer	恢复告警用户ID
items[].tenantId	string	租户ID
items[].createdDept	integer	创建部门
items[].createdBy	integer	创建者
items[].createdAt	string	创建时间
items[].updatedBy	integer	更新者
items[].updatedAt	string	更新时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "alarmRuleId": 1,
        "alarmRuleName": "名称",
        "alarmRuleDescr": "描述",
        "deviceCode": "DEVICE_CODE"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取告警消息

Request Syntax

GET /api/v1/alarm_log/:id/info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	日志ID

Response Data

字段	类型	说明
id	integer	日志ID
alarmRuleId	integer	告警规则ID
alarmRuleName	string	告警规则名称
alarmRuleDescr	string	告警规则描述
deviceCode	string	设备码
deviceName	string	设备名称
alarmLevel	integer	告警级别：1 普通告警，2 重要告警，3 紧急告警。
alarmStatus	integer	告警状态：0 正常，1 告警中，2 待定。
alarmInfo	string	告警信息
triggerInfo	string	触发信息
snapshot	string	设备快照
maintainInfo	string	维护信息
maintainTs	integer	维护更新时间戳秒
maintainer	string	维护信息更新用户
recoverAlarmType	integer	恢复告警类型
recoverAlarmAt	string	恢复告警时间
recoverAlarmRuleId	integer	恢复告警规则ID
recoverAlarmRuleName	string	恢复告警规则名称
recoverTriggerInfo	string	恢复时触发信息
recoverUserType	integer	恢复告警用户类型
recoverUserId	integer	恢复告警用户ID
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "alarmRuleId": 1,
    "alarmRuleName": "名称",
    "alarmRuleDescr": "描述",
    "deviceCode": "DEVICE_CODE",
    "deviceName": "名称",
    "alarmLevel": 1,
    "alarmStatus": 1,
    "alarmInfo": "string",
    "triggerInfo": "string",
    "snapshot": "string",
    "maintainInfo": "string"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改告警历史维护信息

Request Syntax

PUT /api/v1/alarm_log/:id/maintain_info HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	string	是	路径参数

Request Body

字段	类型	必填	说明
id	integer	否	日志ID
alarmReason	string	否	告警原因
solution	string	否	解决方案
remark	string	否	其他备注
isRecover	boolean	否	是否恢复告警

Request Example

{
  "id": 1,
  "alarmReason": "string",
  "solution": "string",
  "remark": "string",
  "isRecover": true
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

读取告警规则列表

Request Syntax

GET /api/v1/alarm_rules HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	规则ID
debugStatus	integer	否	规则调试状态：0 未开启，1 已开启。
dsType	string	否	设备来源类型：device_type 设备类型，device 设备。
dsSource	string	否	设备来源。dsType 为 device 时通常为设备码数组；dsType 为 device_type 时通常为设备类型标识数组。Id
triggerType	string	否	触发类型：attrs_changed 属性变化，inactive 设备不活跃，event_post 事件上报，online 设备在线，offline 设备离线。
createdAt	array<string>	否	创建时间
scanId	integer	否	扫描ID,结合Sort使用
sort	string	否	排序方式(id_asc:ID升序，id_desc:ID降序)

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjAlarmRulesListModel>	数据列表
items[].id	integer	规则ID
items[].name	string	规则名称
items[].descr	string	规则描述
items[].dsType	string	设备来源类型：device_type 设备类型，device 设备。
items[].dsSource	string	设备来源。dsType 为 device 时通常为设备码数组；dsType 为 device_type 时通常为设备类型标识数组。
items[].triggerType	string	触发类型：attrs_changed 属性变化，inactive 设备不活跃，event_post 事件上报，online 设备在线，offline 设备离线。
items[].pendingNum	integer	重复次数
items[].pendingTime	integer	重复时间(秒)
items[].silentTime	integer	静默时间(秒)
items[].conds	string	过滤条件
items[].devicesDisable	string	禁用设备
items[].customTopicIdentifier	string	自定义数据流标识符
items[].alarmLevel	integer	告警级别：1 普通告警，2 重要告警，3 紧急告警。
items[].notificationConfig	string	通知配置 JSON。可包含公众号、短信、电话、App 通知、每日通知次数上限、单设备每日通知次数上限等配置。
items[].enabled	integer	是否启用：0 未启用，1 已启用。
items[].enableTimeSpans	integer	是否启用有效时段：0 未启用，1 已启用。
items[].validTimeSpans	string	有效时段配置 JSON。可包含有效时间段、是否允许解除告警、是否允许用户解除告警、是否允许用户禁用规则等配置。
items[].debugStatus	integer	规则调试状态：0 未开启，1 已开启。
items[].debugEnableTime	integer	规则调试时间
items[].isAlarm	integer	是否处于告警中：0 否，1 是。
items[].isRecoverAlarm	integer	是否为恢复告警规则：0 否，1 是。
items[].recoverAlarmIds	string	恢复告警规则 ID 列表，JSON 数组格式，如 [1,2,3]。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "名称",
        "descr": "描述",
        "dsType": "string",
        "dsSource": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取告警规则信息

Request Syntax

GET /api/v1/alarm_rule/:id HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	规则ID

Response Data

字段	类型	说明
id	integer	规则ID
name	string	规则名称
descr	string	规则描述
dsType	string	设备来源类型：device_type 设备类型，device 设备。
dsSource	string	设备来源。dsType 为 device 时通常为设备码数组；dsType 为 device_type 时通常为设备类型标识数组。
triggerType	string	触发类型：attrs_changed 属性变化，inactive 设备不活跃，event_post 事件上报，online 设备在线，offline 设备离线。
pendingNum	integer	重复次数
pendingTime	integer	重复时间(秒)
silentTime	integer	静默时间(秒)
conds	string	过滤条件
devicesDisable	string	禁用设备
customTopicIdentifier	string	自定义数据流标识符
alarmLevel	integer	告警级别：1 普通告警，2 重要告警，3 紧急告警。
notificationConfig	string	通知配置 JSON。可包含公众号、短信、电话、App 通知、每日通知次数上限、单设备每日通知次数上限等配置。
enabled	integer	是否启用：0 未启用，1 已启用。
enableTimeSpans	integer	是否启用有效时段：0 未启用，1 已启用。
validTimeSpans	string	有效时段配置 JSON。可包含有效时间段、是否允许解除告警、是否允许用户解除告警、是否允许用户禁用规则等配置。
debugStatus	integer	规则调试状态：0 未开启，1 已开启。
debugEnableTime	integer	规则调试时间
isAlarm	integer	是否处于告警中：0 否，1 是。
isRecoverAlarm	integer	是否为恢复告警规则：0 否，1 是。
recoverAlarmIds	string	恢复告警规则 ID 列表，JSON 数组格式，如 [1,2,3]。
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
dsSourceMap	object<string, string>	设备信息

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称",
    "descr": "描述",
    "dsType": "string",
    "dsSource": "string",
    "triggerType": "string",
    "pendingNum": 1,
    "pendingTime": 1626197189,
    "silentTime": 1626197189,
    "conds": "string",
    "devicesDisable": "string",
    "customTopicIdentifier": "string"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

消息规则

读取规则列表

Request Syntax

GET /api/v1/rules HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	规则ID
dsType	string	否	设备来源类型：device_type 设备类型，device 设备。
ruleType	string	否	规则类型
actionType	array<string>	否	动作类型
actionTypeName	array<string>	否	动作类型名称
deviceCode	string	否	设备码
enabled	integer	否	是否启用：0 未启用，1 已启用。
debugStatus	integer	否	规则调试状态：0 未开启，1 已开启。
createdAt	array<string>	否	创建时间
scanId	integer	否	扫描ID,结合Sort使用
sort	string	否	排序方式(id_asc:ID升序，id_desc:ID降序)

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjRulesListModel>	数据列表
items[].id	integer	规则ID
items[].name	string	规则名称
items[].descr	string	规则描述
items[].ruleType	string	规则类型
items[].actionType	array<string>	动作类型
items[].actionTypeName	array<string>	动作类型名称
items[].dsType	string	设备来源类型：device_type 设备类型，device 设备。
items[].customTopicIdentifier	string	自定义数据流标识符
items[].enabled	integer	是否启用：0 未启用，1 已启用。
items[].debugStatus	integer	规则调试状态：0 未开启，1 已开启。
items[].debugEnableTime	integer	规则调试时间
items[].createdAt	string	创建时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "名称",
        "descr": "描述",
        "ruleType": "string",
        "actionType": [
          "string"
        ]
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

读取规则信息

Request Syntax

GET /api/v1/rules/:id HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	规则ID

Response Data

字段	类型	说明
id	integer	规则ID
name	string	规则名称
descr	string	规则描述
ruleType	string	规则类型
dsType	string	设备来源类型：device_type 设备类型，device 设备。
dsSource	string	设备来源。dsType 为 device 时通常为设备码数组；dsType 为 device_type 时通常为设备类型标识数组。
msgConds	string	过滤条件
devicesDisable	string	禁用设备
customTopicIdentifier	string	自定义数据流标识符
eventKey	string	事件标识
enabled	integer	是否启用：0 未启用，1 已启用。
debugStatus	integer	规则调试状态：0 未开启，1 已开启。
debugEnableTime	integer	规则调试时间
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
dsSourceMap	object<string, string>	设备信息
actions	array<internal.model.XjRuleActionsListModelForRules>	规则动作列表
actions[].id	integer	动作ID
actions[].ruleId	integer	规则ID
actions[].type	string	动作类型
actions[].name	string	动作名称
actions[].options	string	动作配置
actions[].orderNum	integer	排序
actions[].createdAt	string	创建时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称",
    "descr": "描述",
    "ruleType": "string",
    "dsType": "string",
    "dsSource": "string",
    "msgConds": "string",
    "devicesDisable": "string",
    "customTopicIdentifier": "string",
    "eventKey": "string",
    "enabled": 1,
    "debugStatus": 1
  },
  "error": null,
  "traceId": "TRACE_ID"
}

设备上下线日志

读取设备上下线日志列表

Request Syntax

GET /api/v1/device/:deviceCode/online_logs HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
deviceCode	string	是	设备码

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	ID
createdAt	array<string>	否	创建时间

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<internal.model.XjDeviceOnlineLogsListModel>	数据列表
items[].id	integer	ID
items[].deviceCode	string	设备码
items[].logType	integer	日志类型：14 上线，15 下线。
items[].logReason	string	下线原因
items[].content	string	日志内容
items[].tenantId	string	租户ID
items[].createdAt	string	创建时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "deviceCode": "DEVICE_CODE",
        "logType": 1,
        "logReason": "string",
        "content": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

应用管理员

应用管理员接口用于项目管理员登录应用并获得应用上下文，令牌载荷中包含 deviceType=saas、appId 与租户信息，除登录接口外均需在请求头携带该令牌。登录账号为项目中 saas_ 前缀（接口会自动补全前缀）的项目管理员账号，且账号需绑定项目管理员权限。

应用管理员登录

Request Syntax

POST /api/v1/app-admin/login HTTP/1.1
Content-Type: application/json

Request Body

字段	类型	必填	说明
appId	integer	是	应用ID
username	string	是	用户名(项目管理员账号)
password	string	是	密码

Request Example

{
  "appId": 1,
  "username": "admin",
  "password": "PASSWORD"
}

Response Data

字段	类型	说明
accessToken	string	应用管理员令牌
expiresAt	string	令牌过期时间
expiresIn	integer	令牌剩余有效时间(秒)
user	internal.model.AppAdminIdentity	应用管理员身份信息
user.userId	integer	用户ID
user.username	string	用户名
user.nickName	string	昵称
user.avatar	string	头像
user.tenantId	string	租户ID
user.appId	integer	应用ID
user.privType	integer	权限类型：1 超级管理员，2 普通用户。
user.permissionKeys	array<string>	权限键列表，超级管理员返回全部权限键
appName	string	应用名称

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "accessToken": "ACCESS_TOKEN",
    "expiresAt": "2026-09-25T12:00:00+08:00",
    "expiresIn": 86400,
    "user": {
      "userId": 1,
      "username": "saas_admin",
      "nickName": "名称",
      "avatar": "string",
      "tenantId": "TENANT_ID",
      "appId": 1,
      "privType": 1,
      "permissionKeys": [
        "operate_device"
      ]
    },
    "appName": "名称"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取当前应用管理员

Request Syntax

GET /api/v1/app-admin/me HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
userId	integer	用户ID
username	string	用户名
nickName	string	昵称
avatar	string	头像
tenantId	string	租户ID
appId	integer	应用ID
privType	integer	权限类型：1 超级管理员，2 普通用户。
permissionKeys	array<string>	权限键列表

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "userId": 1,
    "username": "saas_admin",
    "nickName": "名称",
    "avatar": "string",
    "tenantId": "TENANT_ID",
    "appId": 1,
    "privType": 1,
    "permissionKeys": [
      "operate_device"
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

刷新应用管理员令牌

Request Syntax

POST /api/v1/app-admin/refresh HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
accessToken	string	应用管理员令牌
expiresAt	string	令牌过期时间
expiresIn	integer	令牌剩余有效时间(秒)
user	internal.model.AppAdminIdentity	应用管理员身份信息
user.userId	integer	用户ID
user.username	string	用户名
user.nickName	string	昵称
user.avatar	string	头像
user.tenantId	string	租户ID
user.appId	integer	应用ID
user.privType	integer	权限类型：1 超级管理员，2 普通用户。
user.permissionKeys	array<string>	权限键列表，超级管理员返回全部权限键
appName	string	应用名称

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "accessToken": "ACCESS_TOKEN",
    "expiresAt": "2026-09-26T12:00:00+08:00",
    "expiresIn": 86400,
    "user": {
      "userId": 1,
      "username": "saas_admin",
      "nickName": "名称",
      "avatar": "string",
      "tenantId": "TENANT_ID",
      "appId": 1,
      "privType": 1,
      "permissionKeys": [
        "operate_device"
      ]
    },
    "appName": "名称"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

应用管理员退出登录

Request Syntax

POST /api/v1/app-admin/logout HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

无响应业务字段，服务端会将该令牌加入失效列表。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

获取应用允许访问的看板

Request Syntax

GET /api/v1/app-admin/boards HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
items	array<internal.model.AppAdminBoardListItem>	数据列表
items[].boardId	integer	看板ID
items[].name	string	看板名称
items[].description	string	看板描述
items[].coverUrl	string	看板封面地址

TIP

仅返回应用配置 appConfig.allowViews 中授权、且状态为 ACTIVE 的看板，返回顺序与配置顺序一致；未配置授权看板时 items 为空数组。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "items": [
      {
        "boardId": 1,
        "name": "名称",
        "description": "描述",
        "coverUrl": "string"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取应用看板

Request Syntax

GET /api/v1/app-admin/boards/:boardId HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
boardId	integer	是	看板ID

Response Data

字段	类型	说明
boardId	integer	看板ID
name	string	看板名称
description	string	看板描述
layoutMode	string	布局模式
settingsJson	string	看板设置
language	string	看板语言
components	array<internal.model.VisualBoardPublicComponentModel>	看板组件列表
components[].componentId	integer	组件ID
components[].componentType	string	组件类型
components[].name	string	组件名称
components[].configJson	string	组件配置
components[].dataSourceJson	string	组件数据源配置
components[].posX	integer	组件横坐标
components[].posY	integer	组件纵坐标
components[].width	integer	组件宽度
components[].height	integer	组件高度
components[].zIndex	integer	组件层级

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "boardId": 1,
    "name": "名称",
    "description": "描述",
    "layoutMode": "string",
    "settingsJson": "{}",
    "language": "zh-CN",
    "components": [
      {
        "componentId": 1,
        "componentType": "string",
        "name": "名称",
        "configJson": "{}",
        "dataSourceJson": "[]",
        "posX": 0,
        "posY": 0,
        "width": 0,
        "height": 0,
        "zIndex": 1
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取应用看板数据

Request Syntax

GET /api/v1/app-admin/boards/:boardId/data HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
boardId	integer	是	看板ID

Response Data

字段	类型	说明
components	object<integer, array<internal.model.VisualBoardPublicPoint>>	各组件最新数据，键为组件ID
components[].sourceIndex	integer	数据源索引
components[].deviceCode	string	设备码
components[].key	string	属性或事件标识
components[].value	any	数据值
components[].ts	string	数据时间
errors	object<integer, string>	组件数据获取失败信息，键为组件ID

TIP

这里只返回看板组件已配置数据源中的设备最新值，不是通用的匿名设备查询接口。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "components": {
      "1": [
        {
          "sourceIndex": 0,
          "deviceCode": "DEVICE_CODE",
          "key": "temperature",
          "value": 25.6,
          "ts": "2026-09-25 12:00:00"
        }
      ]
    },
    "errors": {
      "2": "设备离线"
    }
  },
  "error": null,
  "traceId": "TRACE_ID"
}

SaaS 应用

SaaS 应用接口用于获取应用公开配置与当前应用的项目、项目 MQTT 凭据。/api/v1/app-info 免登录，其余接口需要应用管理员令牌。

根据应用ID获取SaaS应用公开配置

Request Syntax

GET /api/v1/app-info HTTP/1.1
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
appId	integer	是	应用ID

Response Data

字段	类型	说明
appId	integer	应用ID
appName	string	应用名称
appDescr	string	应用描述
appConfig	internal.model.SaasAppConfig	应用功能开关配置
appConfig.allowEditDeviceInfo	boolean	是否允许编辑设备信息
appConfig.allowCreateDevice	boolean	是否允许创建设备
appConfig.allowCreateDeviceGroup	boolean	是否允许创建设备分组
appConfig.allowEditDeviceGroup	boolean	是否允许编辑设备分组
appConfig.allowRunTask	boolean	是否允许运行任务
appConfig.allowChangeTaskDeviceStatus	boolean	是否允许启停设备定时任务
appConfig.allowEditTaskCronSettings	boolean	是否允许编辑任务定时设置
appConfig.allowCreateDeviceAlarmRule	boolean	是否允许创建设备告警规则
appConfig.allowPauseDeviceAlarmRule	boolean	是否允许启停设备告警规则
appConfig.allowEditDeviceAlarmRule	boolean	是否允许编辑设备告警规则
appConfig.allowCreateNotificationGroup	boolean	是否允许创建通知组
appConfig.allowEditNotificationGroup	boolean	是否允许编辑通知组
appConfig.allowCreateDeviceAutomateRule	boolean	是否允许创建设备自动化规则
appConfig.allowCreateUser	boolean	是否允许创建用户
appConfig.allowViews	array<string>	允许访问的看板ID列表
styleConfig	internal.model.SaasAppStyleConfig	应用样式配置
styleConfig.globalStylePreset	string	全局样式预设，固定为 architect
styleConfig.globalFixedHeader	boolean	是否固定顶栏
styleConfig.globalFixedSidebar	boolean	是否固定侧边栏
styleConfig.globalFixedFooter	boolean	是否固定页脚
styleConfig.globalHeaderBackgroundMode	string	顶栏背景模式：solid 纯色，gradient 渐变
styleConfig.globalHeaderColor	string	顶栏背景色
styleConfig.globalHeaderGradientColor	string	顶栏渐变背景色
styleConfig.globalHeaderTextColor	string	顶栏文字颜色
styleConfig.globalSidebarBackgroundMode	string	侧边栏背景模式：solid 纯色，gradient 渐变
styleConfig.globalSidebarColor	string	侧边栏背景色
styleConfig.globalSidebarGradientColor	string	侧边栏渐变背景色
styleConfig.globalSidebarTextColor	string	侧边栏文字颜色
styleConfig.globalNavTabsActiveBackgroundColor	string	导航页签选中背景色
styleConfig.globalNavTabsActiveTextColor	string	导航页签选中文字颜色
styleConfig.globalNavTabsActiveFontBold	boolean	导航页签选中是否加粗
styleConfig.globalPageTabsStyle	string	页面页签样式：line 线条，shadow 阴影
styleConfig.globalThemeDark	boolean	是否使用暗色主题
styleConfig.globalColorPrimary	string	主题色
styleConfig.signinShowBgImage	boolean	登录页是否显示背景图
styleConfig.signinBgImage	string	登录页背景图
styleConfig.signinBgImageOpacity	number	登录页背景图透明度
styleConfig.signinDark	boolean	登录页是否使用暗色主题
styleConfig.signinLogoImage	string	登录页 Logo
styleConfig.signinBtnBgColor	string	登录按钮背景色
styleConfig.signinTitleLayout	string	登录页标题布局

TIP

接口仅返回已启用（appStatus=1）且类型为 common_saas 的应用配置；未配置的样式项返回服务端默认值（如 globalPageTabsStyle 非 shadow 时返回 line，背景模式非 gradient 时返回 solid）。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "appId": 1,
    "appName": "名称",
    "appDescr": "描述",
    "appConfig": {
      "allowEditDeviceInfo": true,
      "allowCreateDevice": true,
      "allowCreateDeviceGroup": true,
      "allowEditDeviceGroup": true,
      "allowRunTask": true,
      "allowChangeTaskDeviceStatus": true,
      "allowEditTaskCronSettings": true,
      "allowCreateDeviceAlarmRule": true,
      "allowPauseDeviceAlarmRule": true,
      "allowEditDeviceAlarmRule": true,
      "allowCreateNotificationGroup": true,
      "allowEditNotificationGroup": true,
      "allowCreateDeviceAutomateRule": true,
      "allowCreateUser": true,
      "allowViews": [
        "1"
      ]
    },
    "styleConfig": {
      "globalStylePreset": "architect",
      "globalFixedHeader": true,
      "globalFixedSidebar": true,
      "globalFixedFooter": false,
      "globalHeaderBackgroundMode": "solid",
      "globalHeaderColor": "#ffffff",
      "globalHeaderGradientColor": "#ffffff",
      "globalHeaderTextColor": "#000000",
      "globalSidebarBackgroundMode": "solid",
      "globalSidebarColor": "#ffffff",
      "globalSidebarGradientColor": "#ffffff",
      "globalSidebarTextColor": "#000000",
      "globalNavTabsActiveBackgroundColor": "#ffffff",
      "globalNavTabsActiveTextColor": "#000000",
      "globalNavTabsActiveFontBold": false,
      "globalPageTabsStyle": "line",
      "globalThemeDark": false,
      "globalColorPrimary": "#1677ff",
      "signinShowBgImage": false,
      "signinBgImage": "",
      "signinBgImageOpacity": 1,
      "signinDark": false,
      "signinLogoImage": "",
      "signinBtnBgColor": "#1677ff",
      "signinTitleLayout": "left"
    }
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取当前应用项目

Request Syntax

GET /api/v1/project/current HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
id	string	项目标识(租户ID)
name	string	项目名称
appId	integer	应用ID
appName	string	应用名称
appType	string	应用类型，common_saas 表示通用 SaaS 应用

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": "TENANT_ID",
    "name": "名称",
    "appId": 1,
    "appName": "名称",
    "appType": "common_saas"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取当前项目MQTT凭据

Request Syntax

GET /api/v1/project/mqtt-credentials HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response Data

字段	类型	说明
projectViewKey	string	项目级 MQTT 订阅用户名
projectViewSecret	string	项目级 MQTT 订阅密码

WARNING

该接口返回项目级 MQTT 订阅凭据，响应头带有 Cache-Control: no-store，请勿在客户端缓存或写入日志。项目未配置凭据时接口返回错误。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "projectViewKey": "PROJECT_VIEW_KEY",
    "projectViewSecret": "PROJECT_VIEW_SECRET"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

应用用户

应用用户接口用于管理应用（项目）下的终端用户账号及其设备绑定关系。查询类接口（列表、详情、关联设备）按令牌所属项目过滤数据，使用项目 API 访问令牌或应用管理员令牌均可调用；修改用户信息、重置用户密码、分配用户设备三个写操作要求应用管理员令牌，且管理员需具备对应的权限键（edit_user_info、reset_user_password、assign_user_device）。

获取应用用户列表

Request Syntax

GET /api/v1/project_customers HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Query Parameters

参数	类型	必填	说明
page	integer	否	页码
pageSize	integer	否	每页大小
keyword	string	否	关键字
id	integer	否	用户ID
name	string	否	用户名称
roleName	string	否	角色名称
regFromType	integer	否	注册来源类型：1 平台创建，2 用户注册。
status	integer	否	用户状态：1 已启用，2 未启用。
createdAt	array<string>	否	创建时间
sort	string	否	排序方式(earliest:创建最早,latest:创建最新,recent:最近访问,device_most:设备最多,device_least:设备最少,kanban_most:看板最多,kanban_least:看板最少)

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<v1.XjProjectCustomersListModel>	数据列表
items[].id	integer	用户ID
items[].name	string	用户名称
items[].descr	string	用户描述
items[].account	string	登录名
items[].email	string	邮箱
items[].mobile	string	手机
items[].roleId	integer	角色ID
items[].roleName	string	角色名称
items[].roleDescr	string	角色描述
items[].roleColor	string	角色颜色
items[].emailVerified	integer	邮箱已验证：0 未验证，1 已验证。
items[].mobileVerified	integer	手机已验证：0 未验证，1 已验证。
items[].wxBinded	integer	微信绑定：0 未绑定，1 已绑定。
items[].lastVisitTime	string	最后访问时间
items[].status	integer	用户状态：1 已启用，2 未启用。
items[].regFromType	integer	注册来源类型：1 平台创建，2 用户注册。
items[].createdAt	string	创建时间
items[].deviceCount	integer	绑定设备数量

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "名称",
        "descr": "描述",
        "account": "string",
        "email": "string",
        "mobile": "string",
        "roleId": 1,
        "roleName": "名称",
        "roleDescr": "描述",
        "roleColor": "string",
        "emailVerified": 1,
        "mobileVerified": 1,
        "wxBinded": 1,
        "lastVisitTime": "2026-09-25 12:00:00",
        "status": 1,
        "regFromType": 1,
        "createdAt": "2026-09-25 12:00:00",
        "deviceCount": 1
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

获取应用用户详情

Request Syntax

GET /api/v1/project_customers/:id HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Response Data

字段与「获取应用用户列表」的 items[] 一致。用户不存在时返回业务错误。

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称",
    "descr": "描述",
    "account": "string",
    "email": "string",
    "mobile": "string",
    "roleId": 1,
    "roleName": "名称",
    "roleDescr": "描述",
    "roleColor": "string",
    "emailVerified": 1,
    "mobileVerified": 1,
    "wxBinded": 1,
    "lastVisitTime": "2026-09-25 12:00:00",
    "status": 1,
    "regFromType": 1,
    "createdAt": "2026-09-25 12:00:00",
    "deviceCount": 1
  },
  "error": null,
  "traceId": "TRACE_ID"
}

修改应用用户信息

Request Syntax

PUT /api/v1/project_customers/:id HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Request Body

字段	类型	必填	说明
name	string	是	用户名称
descr	string	否	用户描述
email	string	否	邮箱
mobile	string	否	手机

Request Example

{
  "name": "名称",
  "descr": "描述",
  "email": "string",
  "mobile": "string"
}

Response Data

字段	类型	说明
id	integer	用户ID
name	string	用户名称

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "id": 1,
    "name": "名称"
  },
  "error": null,
  "traceId": "TRACE_ID"
}

重置应用用户密码

Request Syntax

PUT /api/v1/project_customers/:id/password HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Request Body

字段	类型	必填	说明
password	string	是	新密码
confirmPassword	string	是	重复新密码

Request Example

{
  "password": "PASSWORD",
  "confirmPassword": "PASSWORD"
}

Response Data

无响应业务字段。两次输入的密码不一致时返回业务错误。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

获取用户关联设备

Request Syntax

GET /api/v1/project_customers/:id/devices HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Query Parameters

参数	类型	必填	说明
page	integer	否	页码，默认 1
pageSize	integer	否	每页大小，默认 20，最大 200

Response Data

字段	类型	说明
page	integer
pageSize	integer
total	integer
items	array<v1.XjProjectCustomerDevice>	数据列表
items[].id	integer	设备关联ID，移除关联时作为 relationIds 传入
items[].deviceId	integer	设备ID
items[].deviceCode	string	设备码
items[].deviceName	string	设备名称
items[].deviceTypeKey	string	设备类型KEY
items[].deviceTypeName	string	设备类型名称
items[].deviceOnlineStatus	string	设备在线状态
items[].deviceActiveAt	integer	设备活跃时间
items[].deviceBindTime	string	设备关联时间

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "items": [
      {
        "id": 1,
        "deviceId": 1,
        "deviceCode": "DEVICE_CODE",
        "deviceName": "名称",
        "deviceTypeKey": "TYPE_KEY",
        "deviceTypeName": "名称",
        "deviceOnlineStatus": "online",
        "deviceActiveAt": 1626197189,
        "deviceBindTime": "2026-09-25 12:00:00"
      }
    ]
  },
  "error": null,
  "traceId": "TRACE_ID"
}

添加用户关联设备

Request Syntax

POST /api/v1/project_customers/:id/devices HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Request Body

字段	类型	必填	说明
deviceCodes	array<string>	是	设备码列表

Request Example

{
  "deviceCodes": [
    "DEVICE_CODE"
  ]
}

Response Data

无响应业务字段。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

移除用户关联设备

Request Syntax

DELETE /api/v1/project_customers/:id/devices HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Path Parameters

参数	类型	必填	说明
id	integer	是	用户ID

Request Body

字段	类型	必填	说明
relationIds	array<integer>	是	设备关联ID列表

Request Example

{
  "relationIds": [
    1
  ]
}

Response Data

无响应业务字段。关联ID不属于该用户时返回业务错误。

Response Example

{
  "code": 200,
  "message": "",
  "data": {},
  "error": null,
  "traceId": "TRACE_ID"
}

服务信息

服务信息

Request Syntax

GET /api/v1/info HTTP/1.1
Content-Type: application/json

Response Data

字段	类型	说明
type	string
name	string
title	string
description	string
version	string
build	string
commit	string
data	object<string, interface>

Response Example

{
  "code": 200,
  "message": "",
  "data": {
    "type": "string",
    "name": "名称",
    "title": "string",
    "description": "描述",
    "version": "string",
    "build": "string",
    "commit": "string",
    "data": {
      "key": {}
    }
  },
  "error": null,
  "traceId": "TRACE_ID"
}

全局定义

通用响应格式

枚举	取值
设备通信方式 connProtocol	1 WiFi，2 以太网，3 4G，4 5G，5 NB-IoT，6 RS485，7 RS232，8 RS422，9 LoRa，10 Zigbee，11 BLE，99 其他
设备接入类型 connType	1 直连设备，2 子设备，3 网关设备
设备接入协议 msgProtocol	1 内部标准，2 Modbus RTU 透传，3 Modbus TCP 透传，99 其他
设备在线状态 onlineStatus	1 在线，2 离线
设备告警状态 alarmStatus	1 未告警，2 告警中，3 普通告警，4 重要告警，5 紧急告警
设备活跃状态 activeStatus	1 活跃，2 5 分钟内活跃，3 1 小时内活跃，4 1 天内活跃，20 不活跃，21 不活跃超过 1 天，22 不活跃超过 3 天，23 不活跃超过 7 天，30 从未活跃
告警级别 alarmLevel	1 普通告警，2 重要告警，3 紧急告警
告警规则触发类型 triggerType	attrs_changed 属性变化，inactive 设备不活跃，event_post 事件上报，online 设备在线，offline 设备离线
设备来源类型 dsType	device_type 设备类型，device 设备
数据模型属性类型 attrType	report 设备上报，push 云端下发，share 设备云端共享，cloud 云端私有
数据模型数据类型 dataType	integer 整型，decimal 小数，string 字符串，bool 布尔型，enum 枚举型，array 数组型，object 对象型，map_point 地理坐标，map_circle 地理圆形围栏，map_polygon 地理多边形围栏，coords_point 平面坐标，coords_3d_point 三维坐标，daily_timer 每日定时器，daily_timer_range 每日定时区间
消息日志类型 logType	1 属性上报，2 属性上报回复，3 事件上报，4 事件上报回复，5 属性设置，6 属性设置回复，7 功能调用，8 功能调用回复，9 连接事件，10 断开连接事件，11 心跳，12 设备获取平台属性，13 设备获取平台属性回复，14 上线，15 下线，16 属性采集，17 属性采集回复，18 批量上报，19 批量上报回复，20 自定义上报，21 自定义下发回复，22 获取期望值，23 获取期望值回复，24 清除期望值，25 清除期望值回复，26 文件上传，27 文件上传回复

应用侧枚举

枚举	取值
应用类型 appType	common_saas 通用 SaaS 应用
应用状态 appStatus	1 已启用，2 已禁用
应用用户状态 status	1 已启用，2 未启用
应用用户注册来源 regFromType	1 平台创建，2 用户注册
应用用户邮箱验证 emailVerified	0 未验证，1 已验证
应用用户手机验证 mobileVerified	0 未验证，1 已验证
应用用户微信绑定 wxBinded	0 未绑定，1 已绑定
管理员权限类型 privType	1 超级管理员，2 普通用户
管理员权限键 permissionKeys	operate_device 操作设备，view_device_certificate 查看设备证书，edit_device_info 编辑设备信息，edit_device_group 编辑设备分组，change_device_task_status 启用/禁用设备定时任务，change_device_alarm_rule_status 启用/禁用设备告警规则，process_alarm 处理告警，create_user 创建用户，reset_user_password 重设用户密码，assign_user_device 给用户分配设备，edit_user_info 编辑用户信息，change_user_status 编辑用户状态
应用样式预设 globalStylePreset	architect 建筑师风格（当前固定返回该值）
页面页签样式 globalPageTabsStyle	line 线条，shadow 阴影
背景模式 backgroundMode	solid 纯色，gradient 渐变
看板状态 status	ACTIVE 已启用（仅此类看板可被应用访问）