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 和 status 仅包含这些内容。有关完整工作流，请参阅：WebSocket 协议 请参阅。

内容类型

伴随本文的所有 HTTP 请求，Content-Type: application/json 必须发送该消息。WebSocket 消息始终是明文 JSON 帧。

未知键

未识别的键将被默认忽略

该服务目前会无错误地忽略未识别的 JSON 键。如果命令似乎没有生效，请检查服务日志，并将字段名与API 参考文档进行核对。 此行为预计将在未来版本中进行更改（未知键将触发警告事件）。