Home Assistant API 实战指南从查询状态到实时推送的完整接入路径【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io你的应用需要随时知道车库插座通没通电、厨房温度传感器最新读数是多少——而不是让用户自己去 Home Assistant 面板里翻。Home Assistant 的 API 接口就是干这个的一套 HTTP 和消息通道让你的程序能查状态、发命令、收变化。这篇指南带你把三条通道REST、WebSocket、MQTT各自该干的活和接入方法一次讲透跟着做就能跑通第一个请求。什么需求走哪条通道别一上来就研究全部接口先对号入座偶尔查一下、偶尔控一下→ 走 REST API。一问一答的 HTTP 请求最省心适合脚本、后端定时任务。要求状态一变就知道→ 走 WebSocket API。一条长连接挂着事件来了服务端主动推给你不用轮询。接的是 IoT 设备或传感器上报→ 走 MQTT。发布-订阅模式设备只管往主题上发消息谁来听、听几个都行。三条通道共用同一套认证后面统一处理。拿到访问令牌发出第一个请求 所有通道的门槛都是一张访问令牌。推荐用长期访问令牌在 Home Assistant 用户面板的资料页里打开「长期访问令牌」给令牌起个名字比如我的天气脚本生成后复制保存——只显示这一次。之后每个 HTTP 请求带上这个请求头就行Authorization: Bearer 你的令牌。临时访问令牌走的是 OAuth 授权流程适合代表第三方 App 的用户身份流程更复杂新手先用长期令牌。做完这步用一条 curl 验证身份是否有效curl -H Authorization: Bearer 你的令牌 \ http://HA地址:8123/api/返回一段 JSON 配置信息就说明通了。返回 401 就检查令牌复制有没有漏字符。任务一查状态、发控制命令什么时候用定时采集数据、按条件开关某个设备、写个脚本批量操作——这些一问一答的活儿都归 REST API。怎么做查单个实体GET /api/states/实体ID比如sensor.kitchen_temperature。查全部实体GET /api/states返回一个大数组量大时注意分页意识脚本里最好只取需要的字段。发命令POST /api/services/领域/服务请求体里写实体和参数。以打开车库插座为例curl -X POST \ -H Authorization: Bearer 你的令牌 \ -H Content-Type: application/json \ -d {entity_id: switch.garage_outlet} \ http://HA地址:8123/api/services/switch/turn_on预期看到什么命令被接受后返回 200紧接着再查GET /api/states/switch.garage_outletstate字段从off变成onlast_changed时间戳也会刷新。REST 调用本身不返回实体新状态想确认结果就再查一次状态。任务二实时接收状态变化与事件什么时候用轮询太浪费或者变化发生得比你轮询间隔还快比如传感器每秒上报。怎么做连到ws://HA地址:8123/api/websocketWebSocket 就是一种浏览器和服务器之间可双向通信的长连接。连接建好后先发认证再发订阅指令两个消息都是 JSON{id: 1, type: auth, access_token: 你的令牌} {id: 2, type: subscribe_events, event_type: state_changed}预期看到什么认证成功会收到auth_ok类型的应答之后任何一个实体的状态变化服务器都会推一条state_changed事件过来里面同时带着旧值和新值。你的程序只需解析推送、做对应处理即可全程不轮询。任务三用 MQTT 接入 IoT 设备什么时候用设备本身说 MQTT 语言很多传感器、网关都是或者你希望数据发出去、多个系统各自订阅的松耦合结构。怎么做先在 Home Assistant 里启用 MQTT 集成填好 Broker 地址本地常用的自建 Broker 是 Mosquitto用户名密码按 Broker 的配置来。之后设备把数据发布到某个主题例如把温度发到homeassistant/sensor/kitchen/tempHome Assistant 里对应的传感器实体就会自动跟随主题内容更新。反过来你的程序想主动给设备下发指令可以调mqtt.publish服务往主题发消息等价于用 REST 发了一次命令只是消息会经过 Broker 转发给订阅方。预期看到什么用任意 MQTT 客户端订阅同一主题能看到设备上报的原始报文设备一上报sensor.kitchen_temperature的状态立刻变化——这条链路不经过轮询延迟以毫秒计。完整串一遍认证 控制 监听把前面三块拼起来一个最小可用的 Python 程序长这样伪代码级装好requests和websocket-client即可跑# 1. 认证后查一次当前状态 # 2. 发起控制 # 3. 挂上 WebSocket 等推送import requests, json, websocket BASE http://192.168.1.10:8123 H {Authorization: Bearer 你的令牌} requests.post(BASE /api/services/switch/turn_on, headersH, json{entity_id: switch.garage_outlet}) ws websocket.create_connection(ws://192.168.1.10:8123/api/websocket) ws.send(json.dumps({id: 1, type: auth, access_token: 你的令牌})) print(ws.recv()) # 认证应答 ws.send(json.dumps({id: 2, type: subscribe_events, event_type: state_changed})) while True: msg json.loads(ws.recv()) if msg.get(type) event: print(msg[event][data][entity_id], 变了)跑起来后插座先被打开随后终端持续打印状态变化的实体 ID。到这里查询、控制、监听三条线已经闭环。安全与避坑清单逐条过一遍能勾掉一条少一次事故生产环境启用 HTTPS令牌和报文不在公网裸奔给 API 用的程序单独建用户和令牌别复用主账号长期访问令牌写进环境变量或密钥管理工具不提交进代码库令牌定期轮换怀疑泄露立即在用户面板吊销外部接入先走反向代理加白名单 IP别把 8123 直接暴露公网用日志功能抽查 API 调用记录出现陌生调用先查令牌WebSocket 连接要做重连处理网络抖动断开后自动重连并重新订阅收尾发布前自查令牌有效且权限够用401 令牌问题403 权限不够REST 调用后能用状态查询验证结果事件订阅收到过至少一条真实推送断网重连、MQTT Broker 重启后的恢复路径测过一遍各通道的完整参考文档都在仓库里可以直接打开REST 集成说明source/_integrations/api.markdownWebSocket 集成说明source/_integrations/websocket_api.markdownMQTT 集成说明source/_integrations/mqtt.markdownHTTP 集成API 依赖它source/_integrations/http.markdown认证机制source/_docs/authentication.markdown【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考