项目 HTTP API

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

准备工作

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

http

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

TIP

这里的项目 API AccessToken 由 /api/v1/access_token 获取，不是设备证书中的 AccessToken，两者不能混用。

API 请求代码示例

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

shell

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

http

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

Request Body

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

Request Example

json

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

Response Data

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

Response Example

json

{
  "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`	读取设备组树形列表	设备组
POST	`/api/v1/device`	创建设备	设备管理
DELETE	`/api/v1/device/:deviceCode`	删除设备	设备管理
GET	`/api/v1/device/:deviceCode`	读取设备信息	设备管理
PUT	`/api/v1/device/:deviceCode/info`	修改设备基本信息	设备管理
GET	`/api/v1/devices`	读取设备列表	设备管理
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`	获取设备上下线日志列表	设备上下线日志
GET	`/api/v1/info`	服务信息	服务信息

设备类型

获取设备类型列表

Request Syntax

http

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[].createdAt	string	创建时间
items[].deviceCount	integer	设备数量

Response Example

json

{
  "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

http

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	产品默认配置
updateVer	integer	更新版本
tenantId	string	租户ID
createdDept	integer	创建部门
createdBy	integer	创建者
createdAt	string	创建时间
updatedBy	integer	更新者
updatedAt	string	更新时间
deviceCount	integer	设备数量
panelConfig	string	面板配置
userConfig	string	用户配置

Response Example

json

{
  "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

http

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

json

{
  "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

http

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	否	产品默认配置

Request Example

json

{
  "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

json

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

修改设备类型信息

Request Syntax

http

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	否	产品默认配置

Request Example

json

{
  "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

json

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

删除设备类型

Request Syntax

http

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

json

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

设备组

读取设备组树形列表

Request Syntax

http

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

json

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

设备管理

读取设备列表

Request Syntax

http

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 网关设备。
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[].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[].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

json

{
  "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

http

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	设备类型名称
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	网关设备名称

Response Example

json

{
  "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

http

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	否	设备调试时间
address	string	否	设备位置
lat	number	否	设备坐标纬度
lng	number	否	设备坐标经度
regionCode	string	否	行政区域代码
locationBuilding	string	否	建筑
locationUnit	string	否	单元
locationFloor	string	否	楼层
locationRoom	string	否	房号

Request Example

json

{
  "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

json

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

修改设备基本信息

Request Syntax

http

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	否	设备调试时间
address	string	否	设备位置
lat	number	否	设备坐标纬度
lng	number	否	设备坐标经度
regionCode	string	否	行政区域代码
locationBuilding	string	否	建筑
locationUnit	string	否	单元
locationFloor	string	否	楼层
locationRoom	string	否	房号

Request Example

json

{
  "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

json

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

移除设备

Request Syntax

http

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

json

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

设备扩展信息

读取设备扩展信息

Request Syntax

http

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

json

{
  "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

http

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

json

{
  "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

json

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

修改设备扩展信息（PUT）

Request Syntax

http

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

json

{
  "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

json

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

设备数据

读取设备当前属性值集合

Request Syntax

http

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

json

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

读取设备属性历史数据

Request Syntax

http

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

参数	类型	必填	说明
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

json

{
  "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

http

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

参数	类型	必填	说明
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

json

{
  "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

http

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

json

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

Response Data

无响应业务字段。

Response Example

json

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

采集设备属性

Request Syntax

http

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

json

{
  "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

json

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

下发设备属性

Request Syntax

http

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

json

{
  "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

json

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

设备通信

下发命令到设备

Request Syntax

http

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

json

{
  "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

json

{
  "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

http

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

json

{
  "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

http

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

json

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

Response Data

无响应业务字段。

Response Example

json

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

读取设备消息统计

Request Syntax

http

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

json

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

设备告警

读取所有告警消息

Request Syntax

http

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

json

{
  "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

http

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

json

{
  "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

http

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

json

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

Response Data

无响应业务字段。

Response Example

json

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

读取告警规则列表

Request Syntax

http

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

json

{
  "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

http

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

json

{
  "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

http

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

json

{
  "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

http

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

json

{
  "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

http

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

json

{
  "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"
}

服务信息

Request Syntax

http

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

json

{
  "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 文件上传回复

项目 HTTP API ​

准备工作 ​

API 请求代码示例 ​

获取 API AccessToken ​

服务器获取 AccessToken ​

接口总览 ​

设备类型 ​

获取设备类型列表 ​

读取设备类型信息 ​

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

创建设备类型 ​

修改设备类型信息 ​

删除设备类型 ​

设备组 ​

读取设备组树形列表 ​

设备管理 ​

读取设备列表 ​

读取设备信息 ​

创建设备 ​

修改设备基本信息 ​

移除设备 ​

设备扩展信息 ​

读取设备扩展信息 ​

修改设备扩展信息（POST） ​

修改设备扩展信息（PUT） ​

设备数据 ​

读取设备当前属性值集合 ​

读取设备属性历史数据 ​

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

移除设备属性 ​

采集设备属性 ​

下发设备属性 ​

设备通信 ​

下发命令到设备 ​

读取设备配置信息 ​

修改设备配置 ​

读取设备消息统计 ​

设备告警 ​

读取所有告警消息 ​

读取告警消息 ​

修改告警历史维护信息 ​

读取告警规则列表 ​

读取告警规则信息 ​

消息规则 ​

读取规则列表 ​

读取规则信息 ​

设备上下线日志 ​

读取设备上下线日志列表 ​

服务信息 ​

服务信息 ​

全局定义 ​

通用响应格式 ​

项目 HTTP API

准备工作

API 请求代码示例

获取 API AccessToken

服务器获取 AccessToken

接口总览

设备类型

获取设备类型列表

读取设备类型信息

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

创建设备类型

修改设备类型信息

删除设备类型

设备组

读取设备组树形列表

设备管理

读取设备列表

读取设备信息

创建设备

修改设备基本信息

移除设备

设备扩展信息

读取设备扩展信息

修改设备扩展信息（POST）

修改设备扩展信息（PUT）

设备数据

读取设备当前属性值集合

读取设备属性历史数据

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

移除设备属性

采集设备属性

下发设备属性

设备通信

下发命令到设备

读取设备配置信息

修改设备配置

读取设备消息统计

设备告警

读取所有告警消息

读取告警消息

修改告警历史维护信息

读取告警规则列表

读取告警规则信息

消息规则

读取规则列表

读取规则信息

设备上下线日志

读取设备上下线日志列表

服务信息

服务信息

全局定义

通用响应格式