联犀

WebSocket 开发

约 1964 字大约 7 分钟

2025-03-03

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

📋 目录

🔌 连接建立

连接信息

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

请求参数

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

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

连接响应

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

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

响应字段说明：

字段类型说明
codeInteger状态码，200 表示成功
msgString响应消息
handler.TraceparentString链路追踪 ID
handler.connectIDString连接唯一标识符

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

📨 消息格式

基础消息结构

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

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

字段说明

字段类型必填说明
typeString是消息类型，由上下行标识 + 具体方法组成
bodyObject是具体消息参数
body.codeString是消息代码，标识消息类型
body.paramsObject否消息参数，根据具体消息类型而定

消息类型

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

类型说明用途
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"
        }
    }
}

请求参数说明：

参数类型必填说明
typeString是固定值：up.sub
bodyObject是订阅参数
body.codeString是订阅的消息类型代码
body.paramsObject否订阅过滤参数

订阅响应

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

响应参数说明：

参数类型说明
typeString固定值：down.subRet
codeInteger状态码，200 表示成功
msgString响应消息

具体的订阅说明

  1. 物联网相关上报

code说明:

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

params说明:

  • 订阅具体属性
{
  "productID": "xxx",
  "deviceName":"xxx",
  "identifier": "xxx"
}
参数类型说明
productIDString产品名称
deviceNameString设备名称
identifierString属性的ID
  • 订阅设备所有属性
{
  "productID": "xxx",
  "deviceName":"xxx",
}
参数类型说明
productIDString产品名称
deviceNameString设备名称
  • 订阅项目下所有设备 如果设备数量过多可能会导致推送消息过多,需要慎用
{
  "projectID": "xxx"
}
参数类型说明
projectIDString项目ID
  • 订阅某个区域下所有设备 如果设备数量过多可能会导致推送消息过多,需要慎用
{
  "projectID": "xxx",
  "areaID": "xxx"
}
参数类型说明
projectIDString项目ID
areaIDString区域ID

推送消息体说明

  • 设备上报单属性订阅 - devicePropertyReport
{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "identifier": "推送属性的标识符",
  "param":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}
参数类型说明
deviceJSON设备信息
device.productIDString产品id
device.deviceNameString设备名称
timestampString毫秒时间戳
identifierString推送属性的标识符
paramany上报的参数,如果是json类型为对象
param.power_switchBoolean布尔型属性的值一般为0或1
param.colorEnum枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
param.brightnessInteger整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误
  • 设备上报属性订阅第二版(最小版本: v1.3.0) - devicePropertyReportV2
{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "params":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}
参数类型说明
deviceJSON设备信息
device.productIDString产品id
device.deviceNameString设备名称
timestampString毫秒时间戳
identifierString推送属性的标识符
paramsJson上报的参数,key为推送属性的标识符,value为属性的值
  • 设备发布消息 - devicePublish
{
  "productID": "xxx",
  "deviceName":"xxx",
  "content": "xxx",
  "topic":"xxx",
  "action": "xxx",
  "timestamp":"xxx",
  "requestID": "xxx",
  "traceID":"xxx",
  "resultCode": 200,
  "respPayload":"xxx"
}
参数类型说明
productIDString产品id
deviceNameString设备名称
contentString具体信息
topicString主题
actionString操作类型
timestampString操作时间,
requestIDString请求ID
traceIDString服务器端事务id
resultCodeString请求结果状态,200为成功
respPayloadString返回的内容
  • 设备行为消息 - 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"
}
参数类型说明
deviceJSON设备信息
device.productIDString产品id
device.deviceNameString设备名称
timestampString毫秒时间戳
actionIDString行为的标识符
paramsJSONJSON结构内为设备上报的属性值
params.power_switchBoolean布尔型属性的值一般为0或1
params.colorEnum枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
params.brightnessInteger整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误
codeString200为成功
msgString消息
dirString请求方向 up:设备请求云端 down:云端请求设备
reqTypeString请求类型 req resp
  • 设备连接消息 - deviceConn
{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "status": 1
}
参数类型说明
deviceJSON设备信息
device.productIDString产品id
device.deviceNameString设备名称
timestampString毫秒时间戳
statusInteger1:在线 2:离线
  • 设备ota消息推送 - deviceOtaReport
{
  "device": {
    "productID": "产品id",
    "deviceName":"设备名称"
  },
  "timestamp":"毫秒时间戳",
  "status": 1,
  "detail": "",
  "step":10
}
参数类型说明
deviceJSON设备信息
device.productIDString产品id
device.deviceNameString设备名称
timestampString毫秒时间戳
statusInteger1:在线 2:离线
detailString详情
stepInteger当前的升级进度 0-100% -1：升级失败。-2：下载失败。-3：校验失败。-4：烧写失败。

取消消息订阅

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

请求

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

参数说明:

参数类型说明
typeString固定为 up.unSub
bodyboject具体消息的参数
body.codestring订阅的
body.paramsboject订阅的参数

回复

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

参数说明:

参数类型说明
typeString固定为 down.unSubRet
codeint错误码, 200为成功
msgString消息

注意

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

更新日志

2026/8/4 15:04
查看所有更新日志
  • 7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于
  • 054ea-doc于
  • f7d0b-doc于
  • 06463-doc于
  • 7af84-doc于
  • d4fa0-doc: 更换皮肤到最新版于
  • bc770-doc于
  • 4066c-doc: 完善文档于
  • f4017-doc: 完善文档于
  • 8794f-feat: 完善项目`于

联犀 AIoT 平台持续进化中 🚀

📢 查看平台更新说明

微信扫码关注公众号，掌握最新进展；回复“加群”进群