Home Assistant.io API详解：与其他系统集成的接口使用方法
项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io 你是否还在为不同智能家居设备间的数据同步而烦恼？是否想让自己的应用程序实时获取Home Assistant中的设备状态？本文将详细介绍Home Assistant.io提供的API接口，帮助你轻松实现与其他系统的集成，读完你将能够：
- 了解Home Assistant.io的主要API类型及应用场景
- 掌握REST API的认证方式和常用接口调用方法
- 学会使用WebSocket API实现实时数据更新
- 了解MQTT API在设备集成中的应用
API概述
Home Assistant.io提供了多种API接口，以满足不同的集成需求。主要包括REST API、WebSocket API和MQTT API。这些API允许开发者从外部系统访问和控制Home Assistant中的设备和服务，实现更灵活的智能家居控制和数据处理。
API类型对比
| API类型 | 特点 | 适用场景 |
|---|---|---|
| REST API | 基于HTTP协议，请求-响应模式 | 间歇性数据查询、设备控制命令 |
| WebSocket API | 全双工通信，实时性高 | 实时状态更新、事件监听 |
| MQTT API | 基于发布-订阅模式，轻量级 | IoT设备集成、传感器数据上报 |
REST API详解
REST API是Home Assistant.io提供的最基础也最常用的API接口，通过HTTP请求实现对系统的访问和控制。
认证方式
访问Home Assistant REST API需要进行认证，主要有两种方式：长期访问令牌和临时访问令牌。
长期访问令牌
长期访问令牌适用于需要长期访问API的应用。创建方法如下：
- 登录Home Assistant管理界面
- 进入"用户设置" -> "长期访问令牌"
- 点击"创建令牌"，输入名称并保存生成的令牌
使用时，在HTTP请求头中添加：
Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN
临时访问令牌
临时访问令牌通过OAuth2流程获取，适用于第三方应用。详细流程可参考官方文档：认证文档
常用接口示例
获取状态
获取所有实体状态：
GET /api/states
响应示例：
[
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"friendly_name": "Living Room Light"
},
"last_changed": "2023-01-01T12:00:00.000Z"
},
// 更多实体...
]
控制设备
打开客厅灯光：
POST /api/services/light/turn_on
Content-Type: application/json
{
"entity_id": "light.living_room",
"brightness": 200
}
WebSocket API
WebSocket API提供了全双工通信能力，允许客户端与Home Assistant保持持久连接，实时接收状态更新和事件通知。相比REST API，WebSocket API更适合需要实时数据的应用场景。
连接建立
WebSocket连接的URL为：
ws://your-home-assistant-ip:8123/api/websocket
连接建立后需要进行认证，发送包含访问令牌的认证消息：
{
"type": "auth",
"access_token": "YOUR_ACCESS_TOKEN"
}
实时状态更新
认证成功后，可以订阅状态更新事件：
{
"id": 1,
"type": "subscribe_events",
"event_type": "state_changed"
}
当设备状态变化时，Home Assistant会推送事件消息：
{
"id": 1,
"type": "event",
"event": {
"event_type": "state_changed",
"data": {
"entity_id": "light.living_room",
"old_state": {
"state": "off",
// 其他属性...
},
"new_state": {
"state": "on",
// 其他属性...
}
}
}
}
MQTT API
MQTT (Message Queuing Telemetry Transport) 是一种轻量级的消息传输协议，非常适合IoT设备间的通信。Home Assistant通过MQTT API实现与支持MQTT协议的设备集成。
MQTT Broker设置
使用MQTT API前，需要先配置MQTT Broker。Home Assistant推荐使用官方提供的Mosquitto Broker插件，配置方法可参考：MQTT集成文档
发布消息
通过REST API可以向MQTT主题发布消息：
POST /api/services/mqtt/publish
Content-Type: application/json
{
"topic": "homeassistant/switch/1/command",
"payload": "ON",
"qos": 1,
"retain": true
}
订阅消息
在Home Assistant中配置MQTT传感器，订阅特定主题：
sensor:
- platform: mqtt
name: "Temperature"
state_topic: "homeassistant/sensor/temperature"
unit_of_measurement: "°C"
实际应用示例
简单的Python客户端
以下是一个使用REST API控制灯光的Python示例：
import requests
HASS_URL = "http://your-home-assistant-ip:8123"
TOKEN = "your_long_lived_access_token"
headers = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
def turn_on_light(entity_id, brightness=255):
data = {
"entity_id": entity_id,
"brightness": brightness
}
response = requests.post(
f"{HASS_URL}/api/services/light/turn_on",
headers=headers,
json=data
)
return response.status_code == 200
# 打开卧室灯
turn_on_light("light.bedroom", 200)
Node-RED集成
Node-RED是一个基于流的编程工具，非常适合快速构建API集成流程。通过Node-RED的HTTP节点和WebSocket节点，可以轻松实现与Home Assistant的集成。
Node-RED流程图
安全最佳实践
- 使用HTTPS：配置Home Assistant使用HTTPS加密传输，保护API通信安全
- 限制访问权限：为API访问创建专用用户，并只授予必要的权限
- 定期轮换令牌：长期访问令牌应定期轮换，降低泄露风险
- 监控API使用：通过Home Assistant的日志功能监控API访问，及时发现异常
总结
Home Assistant.io提供了REST API、WebSocket API和MQTT API三种主要接口，满足不同场景下的集成需求。REST API适合简单的查询和控制，WebSocket API提供实时数据更新，MQTT API则适用于IoT设备集成。通过这些API，开发者可以构建丰富的应用，扩展Home Assistant的功能。
官方文档提供了更详细的API参考和示例：Home Assistant API文档
如果你有任何问题或集成经验分享，欢迎在社区论坛交流讨论。别忘了点赞、收藏本文，关注我们获取更多Home Assistant使用技巧！
下期预告：Home Assistant自动化进阶：使用API构建智能场景
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
