WebSocket 连接

接口说明

本页说明如何获取实时连接凭证并建立 WebSocket 连接。

客户端须先调用以下 HTTP 接口获取一次性连接令牌与完整的 WebSocket 连接地址，再使用响应中返回的 connect_url 建立 WebSocket 连接。

重要提示：

• 客户端应直接使用响应中的 connect_url 字段建立 WebSocket 连接，不要自行拼接或硬编码连接地址，服务端可能随时调整网关路由。
• 令牌在 ttl_seconds 秒后过期，连接断开或令牌过期后须重新调用本接口获取新令牌。

请求信息

项目	内容
方法	POST
URL	https://devapi.fengshengshou.com/api/devices/{id}/iot-ws-token
鉴权	是，请求头携带 Authorization: Bearer your_token_here

请求参数

参数名	类型	必填	说明
id	int	是	路径参数，设备 ID

本接口无请求体参数。

请求示例

curl -X POST "https://devapi.fengshengshou.com/api/devices/101/iot-ws-token" \
  -H "Authorization: Bearer your_token_here" \
  -H "Accept: application/json"

响应参数

字段	类型	说明
code	int	状态码，0 表示成功
message	string	响应描述
data.device_id	int	设备 ID
data.device_no	string	设备编号
data.token	string	WebSocket 连接令牌
data.expires_at	string	令牌过期时间（格式：Y-m-d H:i:s）
data.ttl_seconds	int	令牌有效时长（秒）
data.connect_url	string	完整 WebSocket 连接地址（含设备编号、角色与令牌），直接使用此字段建立连接
data.iot_ws	object	WebSocket 连接附加信息
data.iot_ws.transport	string	传输协议，固定为 wss
data.iot_ws.path	string	WebSocket 路径
data.iot_ws.role	string	连接角色
data.iot_ws.device_no	string	设备编号
data.iot_ws.connect_url	string	不含令牌的基础连接地址

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "device_id": 101,
    "device_no": "DEV-2024-001",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
    "expires_at": "2026-07-05 10:50:00",
    "ttl_seconds": 1800,
    "connect_url": "wss://iot-gateway.example.com/ws/device/DEV-2024-001?role=viewer&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
    "iot_ws": {
      "transport": "wss",
      "path": "/ws/device/DEV-2024-001",
      "role": "viewer",
      "device_no": "DEV-2024-001",
      "connect_url": "wss://iot-gateway.example.com/ws/device/DEV-2024-001?role=viewer"
    }
  }
}

失败响应

{
  "code": 404,
  "message": "设备不存在",
  "data": null
}

{
  "code": 30004,
  "message": "无设备控制权限",
  "data": null
}