如何通过REST为Home Assistant Sensor设置unique_id及API规范问询

多年前搭建了一款温度传感器，可通过HTTP POST将读数推送到自研服务器/仪表盘系统。因需求扩展，决定切换至Home Assistant（HA）作为后端。虽可向HA发送数据，但文档信息零散，需明确以下内容：

• POST请求体的完整JSON结构（含OpenAPI规范相关说明）
• 传感器与HA交互的工作细节
• 是否可通过设置unique_id让传感器在HA中支持编辑

目前仅基于零散API信息、示例及Python API文档推断开展工作。

一、完整HTTP POST请求体JSON示例 #

基础温度传感器请求体 #

{
  "state": "22.5",
  "attributes": {
    "unit_of_measurement": "°C",
    "device_class": "temperature",
    "friendly_name": "书房温度传感器",
    "unique_id": "custom_temp_sensor_study_001"
  }
}

带扩展属性的请求体 #

{
  "state": 22.5,
  "attributes": {
    "unit_of_measurement": "°C",
    "device_class": "temperature",
    "friendly_name": "书房温度传感器",
    "unique_id": "custom_temp_sensor_study_001",
    "battery_level": 85,
    "last_update": "2024-05-20T14:30:00+08:00",
    "accuracy": 0.1
  }
}

说明：

• state为传感器核心读数，支持字符串或数字类型；
• attributes可包含HA传感器支持的所有属性，字段需符合HA官方规范；
• OpenAPI规范可通过HA内置的/api/swagger.json端点获取，包含所有API请求的结构约束。

二、传感器工作细节 #

• 请求端点：POST请求需发送至HA实例的/api/states/sensor.<自定义实体ID>路径，例如/api/states/sensor.custom_temp_sensor
• 认证要求：请求头必须携带Authorization: Bearer <你的HA长期访问令牌>，令牌可在HA用户设置中生成
• 实体创建逻辑：首次发送请求时，HA会自动创建对应传感器实体；后续请求仅更新实体的状态及属性
• 设备类作用：设置device_class: temperature后，HA会自动匹配对应图标、单位规则及仪表盘展示逻辑，无需额外配置
• 状态更新规则：每次POST请求会覆盖当前传感器的state和attributes，若仅需更新状态，可只传递state字段

三、unique_id设置与传感器可编辑性 #

• 支持设置unique_id：在attributes中添加全局唯一的unique_id字段后，传感器即可在HA前端变为可编辑状态
• 可编辑内容：设置后可在HA界面修改传感器的友好名称、实体ID、图标、设备类等属性，无需再通过API调整
• 注意事项：unique_id一旦设置不可修改，若需更换需先删除原有实体，再发送携带新unique_id的请求

相关文档核心内容（中文提炼） #

REST API核心规则 #

• 所有API请求必须携带认证令牌，支持GET/POST/PUT/DELETE等标准HTTP方法
• 状态类API用于管理实体状态，核心路径为/api/states/<实体ID>
• 可通过/api/states端点查询HA中所有实体的当前状态

HTTP集成传感器规则 #

• 通过POST更新传感器状态时，需指定完整的实体ID路径
• 支持动态创建实体，无需提前在HA配置文件中定义
• 属性字段需符合HA传感器规范，否则可能无法被正常识别

通用传感器设备类规范 #

• device_class用于定义传感器类型，温度传感器需设置为temperature
• 不同设备类对应不同的单位、图标及数据处理逻辑
• 支持的设备类包括温度、湿度、电量等，需根据传感器实际类型选择

内容的提问来源于stack exchange，提问作者QueueHammer