Home API 概览

Android 版 Google Home API 提供了统一的 API 接口，可让开发者与用户住宅中实体的状态进行互动。这些实体可以描述与用户的结构和房间相关联的设备和非设备信息。

Home API 定义了用户可以与之互动的以下实体：

• 结构代表包含房间和设备的住宅。
• 房间是结构的一部分，包含设备。
• 设备会实现包含属性的特征，遵循类型、发出事件并响应命令。
• 自动化操作是结构的一部分，可使用住宅元数据和设备自动执行住宅中的任务。

图 1 展示了此架构：

Home API 设备类型可能由智能家居的开源标准 Matter 支持，也可能是 Google Home 生态系统中的 Cloud-to-cloud 设备。某些设备类型可能同时包含这两种功能。如需了解详情，请参阅支持的设备类型。

在 Matter 中，设备功能按集群分组，集群在 Home API 中表示为 Matter 标准 trait。Home API 支持当前 Matter 规范中定义的一组标准 Matter 集群。

在 Google Home 生态系统中，设备功能会按智能家居 trait 分组，这些 trait 在 Home API 中表示为 Google 智能家居 trait。Home API 支持 Cloud-to-cloud 计划中定义的一组智能家居 trait。

您还可以使用其他 trait，例如特定于制造商的集群和平台 trait。如需了解详情，请参阅数据模型。

语言

Home API 采用 Kotlin 编写，并提供使用 Flow 管理状态和订阅的惯用 Kotlin 接口。与标准订阅 API 相比，这具有多种优势。

如果您还不熟悉，建议您先熟悉 Kotlin 文档中关于协程、Flow 和 Jetpack Compose 的内容：

• 使用 Kotlin 开发 Android 应用
• 了解适用于 Android 的 Kotlin
• Android 上的 Kotlin 协程。以下特定 Codelab 可能对您有所帮助：
  • Codelab - 在 Android 应用中使用 Kotlin 协程
  • Codelab - 通过 Kotlin Flow 和 LiveData 学习高级协程
• Android 上的 Kotlin 数据流，更具体地说，是 StateFlow。
• 状态和 Jetpack Compose，尤其是 collectAsStateWithLifecycle() 函数。此函数会根据显示该状态的界面是否实际位于前台，自动管理对数据流的订阅和取消订阅。
  • Codelab - Jetpack 中的状态
• 如果您使用的是 Automation API，不妨阅读 Kotlin 类型安全构建器，以便了解 Automation DSL 的运作方式。

实体标识符

Home API 中的每个实体都有一个 ID，该 ID 代表其主要标识符。此 ID 是唯一且稳定的标识符，在实体的生命周期内不会发生变化。由于实体的元数据可能会发生变化，因此此 ID 可用于缓存对象或检查是否相等。

请参阅 HasId 接口，了解哪些实体具有 ID。

术语映射

Home API 中的实体与 Matter 和 Cloud-to-cloud 概念对应如下：

Home API	Matter	Cloud-to-cloud
特征	集群	特征
属性	属性	属性、状态
命令	命令	命令
事件	事件	跟进回复、通知