JSON 规范

所有服务接口均采用 JSON 格式。本页面介绍了其通用模式。

端口

港口	接口	版本
10001	HTTP REST + WebSocket（模拟通道）	v3.1（最新版）
10020	WebSocket（事件通道，只读）	—
10000	Legacy-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	Erfolg
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 und status. 参见 WebSocket 协议 了解完整流程。

内容类型

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

未知密钥

未知密钥将被默认忽略

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