WebSocket 开发

约 1964 字大约 7 分钟

2025-03-03

本指南将详细介绍如何使用联犀平台的 WebSocket 服务实现实时通信，包括连接建立、消息订阅、数据推送等功能。

📋 目录

连接建立
消息格式
消息订阅
推送消息
取消订阅
注意事项

🔌 连接建立

连接信息

方法：GET
URL：/api/v1/system/common/websocket/connect
协议：WebSocket

请求参数

支持 Header 参数或 URL 查询参数：

参数名	类型	必填	说明	默认值
`app-code`	String	否	用户正在访问的应用	-
`project-id`	String	是	当前正在访问的项目ID	-
`token`	String	否	用户认证令牌	-
`tenant-code`	String	否	租户代码	`default`

连接响应

连接成功后，服务端会返回以下格式的 JSON 响应：

{
  "code": 200,
  "msg": "成功",
  "handler": {
    "Traceparent": "5a21080b0d1d20a372cb9a1c61e19321",
    "connectID": "29"
  }
}

响应字段说明：

字段	类型	说明
`code`	Integer	状态码，200 表示成功
`msg`	String	响应消息
`handler.Traceparent`	String	链路追踪 ID
`handler.connectID`	String	连接唯一标识符

⚠️ 重要：connectID 是连接的唯一标识符，后续问题排查和连接管理都需要使用此 ID。

📨 消息格式

基础消息结构

所有 WebSocket 消息都遵循以下统一格式：

{
    "type": "up.sub",
    "body": {
        "code": "devicePropertyReport",
        "params": {
            "productID": "k0sr6A5BMbN",
            "deviceName": "cB05016F7"
        }
    }
}

字段说明

字段	类型	必填	说明
`type`	String	是	消息类型，由上下行标识 + 具体方法组成
`body`	Object	是	具体消息参数
`body.code`	String	是	消息代码，标识消息类型
`body.params`	Object	否	消息参数，根据具体消息类型而定

消息类型

上行消息（客户端 → 服务端）

类型	说明	用途
`up.sub`	订阅消息	订阅特定类型的推送消息
`up.unSub`	取消订阅	取消已订阅的消息
`up.ping`	心跳检测	保持连接活跃状态

下行消息（服务端 → 客户端）

类型	说明	用途
`down.subRet`	订阅回复	响应订阅请求
`down.unSubRet`	取消订阅回复	响应取消订阅请求
`down.pub`	消息推送	推送订阅的消息内容
`down.pong`	心跳响应	响应心跳检测

💡 提示：心跳消息（ping/pong）可以发送任意内容，服务端会原样返回。

📡 消息订阅

当应用需要订阅特定类型的消息时，可以通过订阅命令来实现。订阅成功后，相关消息将实时推送给客户端。

订阅请求

{
    "type": "up.sub",
    "body": {
        "code": "devicePropertyReport",
        "params": {
            "productID": "k0sr6A5BMbN",
            "deviceName": "cB05016F7"
        }
    }
}

请求参数说明：

参数	类型	必填	说明
`type`	String	是	固定值：`up.sub`
`body`	Object	是	订阅参数
`body.code`	String	是	订阅的消息类型代码
`body.params`	Object	否	订阅过滤参数

订阅响应

{
    "code": 200,
    "msg": "成功",
    "type": "down.subRet"
}

响应参数说明：

参数	类型	说明
`type`	String	固定值：`down.subRet`
`code`	Integer	状态码，200 表示成功
`msg`	String	响应消息

具体的订阅说明

物联网相关上报

code说明:

code	说明
devicePropertyReport	设备上报单属性订阅
devicePropertyReportV2	设备上报属性订阅第二版(最小版本: v1.3.0)
devicePublish	设备发布消息
deviceActionReport	设备行为消息
deviceEventReport	设备事件消息
deviceConn	设备连接消息
deviceOtaReport	设备ota消息推送

params说明:

订阅具体属性

{
  "productID": "xxx",
  "deviceName":"xxx",
  "identifier": "xxx"
}

参数	类型	说明
productID	String	产品名称
deviceName	String	设备名称
identifier	String	属性的ID

订阅设备所有属性

{
  "productID": "xxx",
  "deviceName":"xxx",
}

参数	类型	说明
productID	String	产品名称
deviceName	String	设备名称

订阅项目下所有设备如果设备数量过多可能会导致推送消息过多,需要慎用

{
  "projectID": "xxx"
}

参数	类型	说明
projectID	String	项目ID

订阅某个区域下所有设备如果设备数量过多可能会导致推送消息过多,需要慎用

{
  "projectID": "xxx",
  "areaID": "xxx"
}

参数	类型	说明
projectID	String	项目ID
areaID	String	区域ID

推送消息体说明

设备上报单属性订阅 - devicePropertyReport

{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "identifier": "推送属性的标识符",
  "param":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}

参数	类型	说明
device	JSON	设备信息
device.productID	String	产品id
device.deviceName	String	设备名称
timestamp	String	毫秒时间戳
identifier	String	推送属性的标识符
param	any	上报的参数,如果是json类型为对象
param.power_switch	Boolean	布尔型属性的值一般为0或1
param.color	Enum	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
param.brightness	Integer	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误

设备上报属性订阅第二版(最小版本: v1.3.0) - devicePropertyReportV2

{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "params":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}

参数	类型	说明
device	JSON	设备信息
device.productID	String	产品id
device.deviceName	String	设备名称
timestamp	String	毫秒时间戳
identifier	String	推送属性的标识符
params	Json	上报的参数,key为推送属性的标识符,value为属性的值

设备发布消息 - devicePublish

{
  "productID": "xxx",
  "deviceName":"xxx",
  "content": "xxx",
  "topic":"xxx",
  "action": "xxx",
  "timestamp":"xxx",
  "requestID": "xxx",
  "traceID":"xxx",
  "resultCode": 200,
  "respPayload":"xxx"
}

参数	类型	说明
productID	String	产品id
deviceName	String	设备名称
content	String	具体信息
topic	String	主题
action	String	操作类型
timestamp	String	操作时间,
requestID	String	请求ID
traceID	String	服务器端事务id
resultCode	String	请求结果状态,200为成功
respPayload	String	返回的内容

设备行为消息 - deviceActionReport

{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "msgToken": "xx",
  "timestamp":"xx",
  "actionID": "xx",
  "params":{
    "power_switch":1,
    "color":1,
    "brightness":32
  },
  "code": 200,
  "msg":"xxx",
  "dir": "up",
  "reqType":"req"
}

参数	类型	说明
device	JSON	设备信息
device.productID	String	产品id
device.deviceName	String	设备名称
timestamp	String	毫秒时间戳
actionID	String	行为的标识符
params	JSON	JSON结构内为设备上报的属性值
params.power_switch	Boolean	布尔型属性的值一般为0或1
params.color	Enum	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
params.brightness	Integer	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误
code	String	200为成功
msg	String	消息
dir	String	请求方向 up:设备请求云端 down:云端请求设备
reqType	String	请求类型 req resp

设备连接消息 - deviceConn

{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "status": 1
}

参数	类型	说明
device	JSON	设备信息
device.productID	String	产品id
device.deviceName	String	设备名称
timestamp	String	毫秒时间戳
status	Integer	1:在线 2:离线

设备ota消息推送 - deviceOtaReport

{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "status": 1,
  "detail": "",
  "step":10
}

参数	类型	说明
device	JSON	设备信息
device.productID	String	产品id
device.deviceName	String	设备名称
timestamp	String	毫秒时间戳
status	Integer	1:在线 2:离线
detail	String	详情
step	Integer	当前的升级进度 0-100% -1：升级失败。-2：下载失败。-3：校验失败。-4：烧写失败。

取消消息订阅

当应用需要取消订阅某个消息的时候,可以通过以下命令来取消订阅

请求

{
    "type": "up.unSub",
    "body": {
        "code":"devicePropertyReport",
        "params":{
            "productID":"k0sr6A5BMbN",
            "deviceName":"cB05016F7"
        }
    }
}

参数说明:

参数	类型	说明
type	String	固定为 up.unSub
body	boject	具体消息的参数
body.code	string	订阅的
body.params	boject	订阅的参数

{
    "code": 200,
    "msg": "成功",
    "type": "down.unSubRet"
}

参数说明:

参数	类型	说明
type	String	固定为 down.unSubRet
code	int	错误码, 200为成功
msg	String	消息

注意

如果连接断开,后端会清除订阅信息,应用需要再重新订阅一次