JSON 规范

所有服务接口均采用 JSON 格式。本页面介绍了常见的模型。

端口

港口	界面	版本
10001	HTTP REST + WebSocket（模拟通道）	v3.1（当前版本）
10020	WebSocket（事件通道，只读）	—
10000	传统 WebSocket（v3.0 — 将在 v4.0 中移除）	v3.0

HTTP 响应封装

每个 HTTP 响应都使用相同的封装：

成功（含数据）：

{ "ok": true, "data": { … } }

成功（无数据——仅修改终点）：

{ "ok": true }

错误：

{ "ok": false, "error": "reason string" }

已弃用的端点：

{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }

HTTP 状态码

代码	含义
200	成功
400	请求错误——正文无效、选择器存在歧义、缺少必填字段
404	找不到设备、会话或资源
405	未授权的方法

WebSocket 消息格式

消息是 JSON 对象。一级键是设备组的名称 (inverse3, verse_grip, wireless_verse_grip) 以及一个可选密钥 session 用于会话级别的命令。

客户 → 服务（订单）：

{
  "session": { "configure": { … } },
  "inverse3": [
    { "device_id": "049D", "configure": { … }, "commands": { … } }
  ]
}

服务 → 客户（状态）：

{
  "session_id": 7,
  "inverse3": [
    { "device_id": "049D", "config": { … }, "state": { … }, "status": { … } }
  ]
}

该服务的首条消息包含 config （完整快照）；后续消息仅包含 state et status. 查看 WebSocket 协议 用于完整的工作流程。

内容类型

所有带有正文的 HTTP 请求都必须发送 Content-Type: application/json. WebSocket 消息始终是明文的 JSON 帧。

未知的钥匙

未知密钥将被静默忽略

该服务目前会忽略未识别的 JSON 键，且不会触发错误。如果某个 命令似乎没有效果，请查看服务日志，并核对API 参考文档中的 字段名称。 此行为将在未来版本中发生变化（未知键 将触发一个警告事件）。