Skip to main content

​
应用WebSocket

​
连接建立

​
/v3/wss/:appId
应用WebSocket连接端点。

​
路径参数

参数名类型必选说明
appIdstring是应用ID

​
查询参数

参数名类型必选说明
tokenstring是访问令牌
连接示例
GET /v3/wss/app123?token=YOUR_ACCESS_TOKEN
连接成功后需要立即发送应用身份验证消息。

​
身份验证

连接建立后，应用需要发送身份验证消息： 
{
  "jsonrpc": "2.0",
  "method": "auth",
  "params": {
    "appId": "app123",
    "token": "YOUR_ACCESS_TOKEN"
  },
  "id": "auth_1"
}
服务器将响应验证结果： 
{
  "jsonrpc": "2.0",
  "result": {
    "appId": "app123",
    "status": "authenticated"
  },
  "id": "auth_1"
}

​
消息类型

​
应用事件

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "type": "status_change",
    "data": {
      "status": "running",
      "timestamp": 1641234567890
    }
  }
}

​
任务通知

{
  "jsonrpc": "2.0",
  "method": "task",
  "params": {
    "taskId": "task123",
    "status": "completed",
    "result": {
      "success": true,
      "data": {}
    }
  }
}

​
资源更新

{
  "jsonrpc": "2.0",
  "method": "resource",
  "params": {
    "type": "update",
    "resource": "database",
    "action": "backup_completed"
  }
}

​
心跳机制

应用需要定期发送心跳包： 
{
  "jsonrpc": "2.0",
  "method": "ping",
  "id": "ping_1"
}
服务器将响应： 
{
  "jsonrpc": "2.0",
  "result": "pong",
  "id": "ping_1"
}
建议每30秒发送一次心跳包，超过90秒未收到心跳响应则重新连接。

​
错误处理

​
常见错误

  1. 应用认证失败
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Application authentication failed",
    "data": {
      "reason": "Invalid application ID"
    }
  },
  "id": "auth_1"
}
  1. 资源访问失败
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "Access denied",
    "data": {
      "resource": "database",
      "reason": "Insufficient permissions"
    }
  },
  "id": "resource_1"
}

​
重连策略

  1. 网络断开时立即尝试重连
  2. 失败后采用指数退避策略
  3. 最大重试间隔为5分钟
  4. 重连成功后重新进行应用身份验证

错误码说明

错误码说明
-32001应用认证失败
-32002权限不足
-32602无效参数
-32603内部错误