规则与热重载接口

这五条都在写组：只认 Bearer，面板的会话 cookie 在这里一律 401 （分界见总览）。

规则怎么写见 automations/*.toml；改配置到生效的完整流程 见热重载；排查“昨晚风扇为什么自己开了”见 出了问题怎么查。这一页只讲接口本身。

改规则前先看 trace

/api/rules/{name}/trace 答的是「为什么触发了」「为什么没触发」—— outcome 说 结局，detail 说原因，commands 是这次派发出去的命令 id。

先看它再动手改，否则你改的可能根本不是出问题的那一环。记录存在内存里的 环形缓冲，重启即失。

curl -s -H "Authorization: Bearer $RHA_TOKEN" \
  'http://127.0.0.1:8420/api/rules/hot/trace?limit=5' | jq '.data[]'

写规则是全量校验的

POST /api/rules 和 DELETE /api/rules/{name} 都是写盘 → 全量 check → 失败回滚。所以不会出现「新规则写坏了，把旧规则也带没了」这种事。

# 覆盖一条规则
curl -s -X POST -H "Authorization: Bearer $RHA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"hot","toml":"trigger = { type = \"above\", entity = \"t.temp\", threshold = 28 }\nactions = [{ type = \"set\", entity = \"fan.power\", value = true }]\n"}' \
  http://127.0.0.1:8420/api/rules | jq .

# 让盘上改动生效
curl -s -X POST -H "Authorization: Bearer $RHA_TOKEN" \
  http://127.0.0.1:8420/api/reload | jq .data

reload 管不了的东西

[api]、[storage] 和 bridges.toml 改了必须重启进程。这类改动 reload 会 明确拒绝并在 error 里说清楚，不会假装成功 —— 假装成功是最坏的：你以为配好了， 其实跑的还是旧的。

GET/api/rules

认证：Bearer token

返回的是当前这一代规则, 即最近一次成功 reload 之后的。盘上文件改了但还没 reload 时, 这里看到的仍是旧的。

返回

成功时 data 字段的形状：

数组，每个元素：

字段	类型	说明
actions*	array	—
condition	any	—
mode*	string	—
name*	string	—
throttle*	object	—
trigger*	any	—

POST/api/rules

认证：Bearer token

按 name 覆盖同名规则。写盘后全量 check, 任一条规则不合法就整体回滚 —— 不会出现「新规则写坏了, 旧规则也跟着没了」。

name 只能是 [a-z0-9_], 1-64 字符; toml 是规则文件的完整内容。

请求体

字段	类型	说明
name*	string	—
toml*	string	—

返回

成功时 data 字段的形状：

一个对象：

字段	类型	说明
actions*	integer	—
entities*	integer	—
rules*	integer	—

错误

• 400 —— 规则名不合法, 或 TOML 解析/校验失败(error 里是逐条原因)

DELETE/api/rules/{name}

认证：Bearer token

连同它的文件一起删。与新增同样是全量 check 后才生效。

参数

参数	位置	类型	说明
name*	路径	string	规则名, [a-z0-9_], 1-64 字符

返回

成功时 data 字段的形状：

一个对象：

字段	类型	说明
actions*	integer	—
entities*	integer	—
rules*	integer	—

错误

• 400 —— 规则名不合法
• 404 —— 没有这条规则

GET/api/rules/{name}/trace

认证：Bearer token

改规则前先看这个。 它答的是「为什么触发了」「为什么没触发」—— outcome 说结局, detail 说原因, commands 是这次派发出去的命令 id。

记录来自常驻内存的环形缓冲, 重启即失。limit 缺省 20。

参数

参数	位置	类型	说明
name*	路径	string	规则名
limit	查询串	integer	最多返回多少条, 缺省 20

返回

成功时 data 字段的形状：

数组，每个元素：

字段	类型	说明
commands*	array	—
detail*	string	—
event*	string	事件的 Display 摘要
outcome*	string	&'static str 没有 JsonSchema 实现, 对外就是普通字符串。
rule*	string	—
ts*	string date-time	—

错误

• 400 —— limit 不是整数
• 404 —— 没有这条规则

POST/api/reload

认证：Bearer token

check-then-swap: 先全量校验, 通过了才换代, 任一处不合法就整体不动。返回换代后的实体/规则/动作条数。

不是所有配置都能热加载。 [api]、[storage] 与 bridges.toml 改了必须重启进程 —— 这类改动 reload 会明确拒绝并在 error 里说清楚, 不会假装成功。

返回

成功时 data 字段的形状：

一个对象：

字段	类型	说明
actions*	integer	—
entities*	integer	—
rules*	integer	—

错误

• 400 —— 校验失败, 或改了必须重启才能生效的配置(error 里是逐条原因)