1. Home Assistant REST API基础入门第一次接触Home Assistant的REST API时我完全被它强大的跨品牌整合能力震撼了。想象一下你家里的小米风扇、美的空调、飞利浦灯泡都能通过同一个界面控制这就是REST API的魅力所在。简单来说它就像个万能翻译官让不同品牌的智能设备说同一种语言。核心概念三要素你需要先掌握Endpoint端点每个设备对应的唯一URL地址比如/api/services/fan/turn_on就是控制风扇开启的入口HTTP方法最常用的是POST执行操作和GET获取状态认证方式Bearer Token是当前最安全的认证机制相当于你的个人电子钥匙我刚开始用的时候犯过一个典型错误直接在浏览器地址栏输入API地址结果返回401错误。后来才发现必须用专门的工具如Postman或curl发送带认证头的请求。这里有个新手容易忽略的细节HTTP头部必须包含两个关键字段Authorization: Bearer your_long_token Content-Type: application/json2. 跨品牌设备控制实战2.1 小米设备接入详解以小米智能风扇为例通过API控制需要三步走获取设备指纹curl -X GET \ -H Authorization: Bearer YOUR_TOKEN \ http://your-ha-ip:8123/api/states在返回的JSON中找到类似fan.xiaomi_fan的entity_id这就是设备的唯一标识。风速调节技巧import requests url http://your-ha-ip:8123/api/services/fan/set_percentage headers { Authorization: Bearer YOUR_TOKEN, Content-Type: application/json } data { entity_id: fan.xiaomi_fan, percentage: 50 # 50%风速 } response requests.post(url, headersheaders, jsondata)实测发现风速百分比不是线性变化的小米风扇在30%以下几乎无声60%以上噪音明显增大。摆头控制陷阱service: fan.oscillate data: entity_id: fan.xiaomi_fan oscillating: true注意部分旧款小米风扇的摆头角度需要通过额外参数angle指定新固件可能不支持这个参数。2.2 美的空调特殊处理美的设备接入有个大坑必须通过Midea AC LAN组件。我花了三天才搞明白的配置流程在HACS中安装Midea AC LAN组件通过美的美居APP获取设备ID藏在高级设置里关键配置代码midea_ac_lan: devices: - device_id: 123456789 ip: 192.168.1.100 port: 6444 token: xxxxxxxx protocol: 3 # 这个数字因机型而异踩过的坑美的空调的protocol版本直接影响功能可用性新款机型可能需要设为2老款用3。3. 自动化进阶技巧3.1 多设备联动场景这是我家的真实场景配置当温度28℃且有人在房间时自动开启空调和风扇automation: - alias: Cooling Automation trigger: - platform: numeric_state entity_id: sensor.temperature above: 28 - platform: state entity_id: binary_sensor.motion_sensor to: on condition: and action: - service: climate.turn_on target: entity_id: climate.midea_ac - service: fan.turn_on target: entity_id: fan.xiaomi_fan - delay: 00:10:00 # 10分钟后调低风速 - service: fan.set_percentage data: percentage: 30 entity_id: fan.xiaomi_fan3.2 异常处理机制自动化最怕的就是设备无响应我的解决方案是加入重试逻辑from tenacity import retry, stop_after_attempt, wait_fixed retry(stopstop_after_attempt(3), waitwait_fixed(2)) def control_device(entity_id, service): try: hass.services.call(service.split(.)[0], service.split(.)[1], {entity_id: entity_id}) except Exception as e: logger.error(fControl failed: {str(e)}) raise4. 安全与性能优化4.1 认证安全实践千万别把长时效token写在配置文件里我现在的做法是创建短期有效的token7天使用Home Assistant的Secrets功能管理通过环境变量注入rest_command: turn_on_fan: url: http://localhost:8123/api/services/fan/turn_on method: POST headers: Authorization: !secret api_token content_type: application/json4.2 性能调优经验当你有50设备时API响应速度可能变慢。这几个优化立竿见影启用HTTP压缩在configuration.yaml添加http: use_x_forwarded_for: true ip_ban_enabled: true login_attempts_threshold: 5 compress: true # 关键配置使用websocket替代RESTWebsocket连接能减少70%的延迟批量操作接口避免频繁调用单个设备接口5. 调试与问题排查遇到API返回404时先用开发者工具检查可用服务访问/api/services查找对应domain如fan/climate确认service名称如turn_on/set_temperature我整理的常见错误代码速查表错误码含义解决方案401认证失败检查token是否过期404接口不存在确认domain/service拼写422参数错误检查JSON数据格式500服务端错误查看Home Assistant日志最后分享个实用技巧在开发者工具 - 服务里测试API调用可以自动生成正确的YAML代码比手动写curl方便多了。