Skip to main content

实体注册

实体注册是 Home Assistant 记录实体的注册表。任何添加到 Home Assistant 的实体,如果指定了 unique_id 属性,都会被注册到注册表中。

注册的优点在于,同一个实体将始终获得相同的实体 ID。这也将防止其他实体使用该实体 ID。

用户还可以在实体注册中覆盖实体的名称。设置后,实体注册中的名称将优先于设备可能自我提供的名称。

唯一 ID

用户无法更改唯一 ID 这一点非常重要,因为系统将失去与唯一 ID 相关的所有设置。

实体根据平台类型(例如 light)、集成名称(域)(例如 hue)和实体的唯一 ID 的组合在注册表中进行查找。实体的唯一 ID 中不应包含 domain(例如 your_integration)和平台类型(例如 light),因为系统已经考虑到了这些标识符。

如果一个设备具有唯一的 id,但提供多个实体,则将唯一 id 与实体的唯一标识符结合。例如,如果一个设备同时测量温度和湿度,可以使用 {unique_id}-{sensor_type} 唯一识别这些实体。

唯一 ID 要求

可接受的唯一 ID 示例来源

  • 设备的序列号
  • MAC 地址:使用 homeassistant.helpers.device_registry.format_mac 格式化;只能从设备 API 或发现处理程序获得 MAC 地址。依赖于读取 arp 缓存或本地网络访问的工具,如 getmac,在所有支持的网络环境中可能无法正常工作,因此不被接受。
  • 纬度和经度或其他唯一地理位置
  • 物理上打印在设备上或烧录到 EEPROM 中的唯一标识符

最后手段的唯一 ID

对于通过配置条目设置的实体,如果没有其他唯一 ID 可用,可以使用 配置条目 ID 作为最后手段。

不可接受的唯一 ID 来源

  • IP 地址
  • 设备名称
  • 主机名
  • URL
  • 电子邮件地址
  • 用户名