Home Assistant.io API详解：与其他系统集成的接口使用方法

你是否还在为不同智能家居设备间的数据同步而烦恼？是否想让自己的应用程序实时获取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的应用。创建方法如下：

1. 登录Home Assistant管理界面
2. 进入"用户设置" -> "长期访问令牌"
3. 点击"创建令牌"，输入名称并保存生成的令牌

使用时，在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流程图

安全最佳实践

1. 使用HTTPS：配置Home Assistant使用HTTPS加密传输，保护API通信安全
2. 限制访问权限：为API访问创建专用用户，并只授予必要的权限
3. 定期轮换令牌：长期访问令牌应定期轮换，降低泄露风险
4. 监控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构建智能场景