Home Assistant API接入手册REST、WebSocket、MQTT 三种接口一次讲清【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io你的App想实时拿到客厅灯的状态该走哪条路我们用三个真实任务跑通 Home Assistant API 的三种对外接口REST API 查一次状态、WebSocket 持续推送、MQTT 对接设备完成一次完整的智能家居集成。30秒选路三种接口怎么选这一节只干一件事按你的任务直接跳到对应章节不展开协议原理。你的任务走哪条路跳到查一次状态、发一条控制命令REST API任务一要持续拿到状态变化推送WebSocket任务二要对接只会说 MQTT 的设备MQTT任务三原则就一条任务决定接口而不是反过来。拿不准就先走任务一它是上手最快的一条路跑通之后再回来升级。任务一用 REST API 完成第一次设备控制这一节解决第一次调用以打开一盏灯为最小完整案例走完认证、构造请求、读响应三步。创建长期访问令牌先给脚本发一个长期访问令牌long-lived access token一次创建、长期有效的调用凭证登录管理界面打开 用户资料 安全在长期访问令牌卡片里创建并命名创建时可以加一句用途备注方便以后辨认令牌只显示一次立刻存好。下面这段 Python 代码带着 Bearer 令牌发送一个服务调用点亮客厅灯并把亮度设为 200import requests HASS_URL http://你的HA地址:8123 TOKEN 你的长期访问令牌 resp requests.post( f{HASS_URL}/api/services/light/turn_on, headers{Authorization: fBearer {TOKEN}}, json{entity_id: light.living_room, brightness: 200}, ) print(resp.status_code) print(resp.json())返回 200 并打印出实体最新状态说明 Home Assistant REST API 认证和调用都跑通了返回 401 就检查令牌有没有带对。URL 的结构也值得记一下/api/services 后面接 领域/服务这里是 light/turn_on——你几乎不需要背接口文档在前端服务调用面板里看一眼就能照抄。想手动验证的话用 curl 带同样的 Authorization 头请求 /api/states能拉到全部实体的状态列表。任务二用 WebSocket 把状态变化实时推到自己的App这一节解决REST 轮询太费事改用 WebSocket 实时状态推送状态一变立刻送到你的App。用 REST 你只能每隔几秒问一次灯变了吗有延迟还空耗请求WebSocket全双工的持久连接服务器能主动推消息给你正好反过来连上之后状态一变就推过来免轮询。先连接 ws://你的HA地址:8123/api/websocket发一条 type 为 auth 的消息完成认证再发一条订阅消息盯住 state_changed 事件。下面这段代码完整走通连接、认证、订阅、收推送import asyncio, json, websockets async def main(): async with websockets.connect(ws://你的HA地址:8123/api/websocket) as ws: await ws.send(json.dumps({type: auth, access_token: 你的长期访问令牌})) print(await ws.recv()) await ws.send(json.dumps({id: 1, type: subscribe_events, event_type: state_changed})) while True: msg json.loads(await ws.recv()) if msg.get(type) event: print(msg[event][data][entity_id], msg[event][data][new_state][state]) asyncio.run(main())第一句打印的是认证成功回执连接断开后循环会抛异常正式跑之前记得加重连逻辑。收到推送时报文长这样——entity_id 和 new_state 里的值就是你要的数据{ id: 1, type: event, event: { event_type: state_changed, data: { entity_id: light.living_room, old_state: { state: off }, new_state: { state: on } } } }注意每条请求都要带递增的 idHA 的回执会回传同一个 id方便你配对请求与结果。任务三MQTT 设备集成配置如果你的设备本身只说 MQTT那就走这条路。这一节解决传感器与IoT设备怎么接进 Home Assistant。MQTT一种轻量级的发布/订阅消息协议设备各发各的主题由 Broker 负责转发接入有两个前置条件按 官方MQTT集成文档 在 HA 里配好 MQTT 集成连上一个 Broker如 Mosquitto并在日志里看到 connected。先用这条命令向主题发布一条命令报文让 HA 侧的开关实体收到 ONmosquitto_pub -h 127.0.0.1 -p 1883 -t homeassistant/switch/1/command -m ON反过来要让 HA 订阅一个传感器主题在配置里加一个 MQTT 传感器即可mqtt: sensor: - name: Temperature state_topic: homeassistant/sensor/temperature unit_of_measurement: °C保存并重启后HA 里会多出一个对应实体主题上的 payload 可以是纯文本也可以是 JSON它更新实体状态就跟着变。Home Assistant REST API 认证长期令牌还是 OAuth2 临时令牌前面两个任务默认都用长期令牌这一节把两种方式横向对比帮你对号入座。长期访问令牌适合个人脚本和自己写的App在内网长期挂着调用。步骤登录管理界面 → 用户资料 安全 → 创建长期访问令牌可以备注用途之后每个请求带上 Authorization: Bearer 令牌 即可。OAuth2 临时令牌适合代表用户访问的第三方应用走标准授权流程换到短期令牌和 refresh token过期后刷新泄露窗口小适合产品化的智能家居集成场景。个人项目用不到就别上徒增复杂度。上生产前必做的安全清单这一节把智能家居 API 安全实践浓缩成五条发布前逐条过一遍。全程走 HTTPS别让令牌在网络上明文跑给 API 访问建专用低权限用户别用 owner 账户令牌定期轮换怀疑泄露立即删除重建打开日志监控 API 访问陌生来源及时处置能用内网隔离就别暴露公网必须公网可达时叠加多因素认证写在最后三种接口分工一句话REST 管查一次、控一次WebSocket 管实时状态推送MQTT 管设备对接按任务选路就行。更完整的端点与消息参考见 官方API文档。哪一步卡住了欢迎到社区论坛发帖把报错信息带上大家一起排。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Assistant API接入手册：REST、WebSocket、MQTT 三种接口一次讲清
Home Assistant API接入手册REST、WebSocket、MQTT 三种接口一次讲清【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io你的App想实时拿到客厅灯的状态该走哪条路我们用三个真实任务跑通 Home Assistant API 的三种对外接口REST API 查一次状态、WebSocket 持续推送、MQTT 对接设备完成一次完整的智能家居集成。30秒选路三种接口怎么选这一节只干一件事按你的任务直接跳到对应章节不展开协议原理。你的任务走哪条路跳到查一次状态、发一条控制命令REST API任务一要持续拿到状态变化推送WebSocket任务二要对接只会说 MQTT 的设备MQTT任务三原则就一条任务决定接口而不是反过来。拿不准就先走任务一它是上手最快的一条路跑通之后再回来升级。任务一用 REST API 完成第一次设备控制这一节解决第一次调用以打开一盏灯为最小完整案例走完认证、构造请求、读响应三步。创建长期访问令牌先给脚本发一个长期访问令牌long-lived access token一次创建、长期有效的调用凭证登录管理界面打开 用户资料 安全在长期访问令牌卡片里创建并命名创建时可以加一句用途备注方便以后辨认令牌只显示一次立刻存好。下面这段 Python 代码带着 Bearer 令牌发送一个服务调用点亮客厅灯并把亮度设为 200import requests HASS_URL http://你的HA地址:8123 TOKEN 你的长期访问令牌 resp requests.post( f{HASS_URL}/api/services/light/turn_on, headers{Authorization: fBearer {TOKEN}}, json{entity_id: light.living_room, brightness: 200}, ) print(resp.status_code) print(resp.json())返回 200 并打印出实体最新状态说明 Home Assistant REST API 认证和调用都跑通了返回 401 就检查令牌有没有带对。URL 的结构也值得记一下/api/services 后面接 领域/服务这里是 light/turn_on——你几乎不需要背接口文档在前端服务调用面板里看一眼就能照抄。想手动验证的话用 curl 带同样的 Authorization 头请求 /api/states能拉到全部实体的状态列表。任务二用 WebSocket 把状态变化实时推到自己的App这一节解决REST 轮询太费事改用 WebSocket 实时状态推送状态一变立刻送到你的App。用 REST 你只能每隔几秒问一次灯变了吗有延迟还空耗请求WebSocket全双工的持久连接服务器能主动推消息给你正好反过来连上之后状态一变就推过来免轮询。先连接 ws://你的HA地址:8123/api/websocket发一条 type 为 auth 的消息完成认证再发一条订阅消息盯住 state_changed 事件。下面这段代码完整走通连接、认证、订阅、收推送import asyncio, json, websockets async def main(): async with websockets.connect(ws://你的HA地址:8123/api/websocket) as ws: await ws.send(json.dumps({type: auth, access_token: 你的长期访问令牌})) print(await ws.recv()) await ws.send(json.dumps({id: 1, type: subscribe_events, event_type: state_changed})) while True: msg json.loads(await ws.recv()) if msg.get(type) event: print(msg[event][data][entity_id], msg[event][data][new_state][state]) asyncio.run(main())第一句打印的是认证成功回执连接断开后循环会抛异常正式跑之前记得加重连逻辑。收到推送时报文长这样——entity_id 和 new_state 里的值就是你要的数据{ id: 1, type: event, event: { event_type: state_changed, data: { entity_id: light.living_room, old_state: { state: off }, new_state: { state: on } } } }注意每条请求都要带递增的 idHA 的回执会回传同一个 id方便你配对请求与结果。任务三MQTT 设备集成配置如果你的设备本身只说 MQTT那就走这条路。这一节解决传感器与IoT设备怎么接进 Home Assistant。MQTT一种轻量级的发布/订阅消息协议设备各发各的主题由 Broker 负责转发接入有两个前置条件按 官方MQTT集成文档 在 HA 里配好 MQTT 集成连上一个 Broker如 Mosquitto并在日志里看到 connected。先用这条命令向主题发布一条命令报文让 HA 侧的开关实体收到 ONmosquitto_pub -h 127.0.0.1 -p 1883 -t homeassistant/switch/1/command -m ON反过来要让 HA 订阅一个传感器主题在配置里加一个 MQTT 传感器即可mqtt: sensor: - name: Temperature state_topic: homeassistant/sensor/temperature unit_of_measurement: °C保存并重启后HA 里会多出一个对应实体主题上的 payload 可以是纯文本也可以是 JSON它更新实体状态就跟着变。Home Assistant REST API 认证长期令牌还是 OAuth2 临时令牌前面两个任务默认都用长期令牌这一节把两种方式横向对比帮你对号入座。长期访问令牌适合个人脚本和自己写的App在内网长期挂着调用。步骤登录管理界面 → 用户资料 安全 → 创建长期访问令牌可以备注用途之后每个请求带上 Authorization: Bearer 令牌 即可。OAuth2 临时令牌适合代表用户访问的第三方应用走标准授权流程换到短期令牌和 refresh token过期后刷新泄露窗口小适合产品化的智能家居集成场景。个人项目用不到就别上徒增复杂度。上生产前必做的安全清单这一节把智能家居 API 安全实践浓缩成五条发布前逐条过一遍。全程走 HTTPS别让令牌在网络上明文跑给 API 访问建专用低权限用户别用 owner 账户令牌定期轮换怀疑泄露立即删除重建打开日志监控 API 访问陌生来源及时处置能用内网隔离就别暴露公网必须公网可达时叠加多因素认证写在最后三种接口分工一句话REST 管查一次、控一次WebSocket 管实时状态推送MQTT 管设备对接按任务选路就行。更完整的端点与消息参考见 官方API文档。哪一步卡住了欢迎到社区论坛发帖把报错信息带上大家一起排。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考