Home API 總覽

Android 版 Google Home API 提供統一的 API 介面，讓開發人員能夠與使用者家中的實體狀態互動。這些實體可描述與使用者結構和房間相關聯的裝置和非裝置資訊。

Home API 定義了使用者可互動的實體：

• 結構代表住家，包含房間和裝置。
• 房間是建築結構的一部分，並包含裝置。
• Devices 會實作包含屬性的特徵、符合類型、發出事件，以及回應指令。
• 自動化動作是結構體的一部分，可使用住家中繼資料和裝置，自動執行住家中的任務。

圖 1 說明此架構：

Home API 裝置類型可能會由 Matter 支援，這是智慧住宅的開放標準，或是 Google Home 生態系統中的 Cloud-to-cloud 裝置。部分裝置類型可能會整合這兩種功能。詳情請參閱「支援的裝置類型」。

在 Matter 中，裝置功能會依叢集分組，這些叢集會在 Google Home API 中以 Matter 標準特徵表示。Home API 支援目前 Matter 規範中定義的標準 Matter 叢集。

在 Google Home 生態系統中，裝置功能會依智慧住宅特徵分組，這些特徵在 Google Home API 中會以 Google 智慧住宅特徵表示。Home API 支援 Cloud-to-cloud 計畫中定義的智慧住宅特徵組合。

您也可以使用其他特徵，例如製造商專屬叢集和平台特徵。詳情請參閱「資料模型」。

語言

Home API 是以 Kotlin 編寫，並提供慣用的 Kotlin 介面，使用 Flow 管理狀態和訂閱。這比標準訂閱 API 提供更多優勢。

建議您熟悉 Kotlin 協同程式、流程和 Jetpack Compose 相關文件：

• 使用 Kotlin 開發 Android 應用程式
• 瞭解 Android 適用的 Kotlin
• Android 上的 Kotlin 協同程式。以下程式碼研究室可能會派上用場：
  • 程式碼研究室 - 在 Android 應用程式中使用 Kotlin 協同程式
  • 程式碼研究室：透過 Kotlin 資料流和 LiveData 瞭解進階協同程式
• Android 上的 Kotlin 資料流，具體來說是 StateFlow。
• 狀態和 Jetpack Compose，特別是 collectAsStateWithLifecycle() 函式。這個函式會根據 UI 顯示該狀態是否實際處於前景，自動管理訂閱和取消訂閱流程。
  • 程式碼研究室 - Jetpack 中的狀態
• 如果您要使用 Automation API，請參閱 Kotlin 型別安全建構工具，瞭解 Automation DSL 的運作方式。

實體 ID

Home API 中的每個實體都有 ID，代表其主要 ID。這個 ID 是獨特且穩定的識別碼，在實體的生命週期內絕不會變更。實體的中繼資料可能會變更，因此這個 ID 可用於快取物件或檢查相等性。

請參閱 HasId 介面，瞭解哪些實體有 ID。

術語對應

Home API 中的實體會對應至 Matter 和 Cloud-to-cloud 概念，如下所示：

Home API	Matter	Cloud-to-cloud
特徵	叢集	特徵
屬性	屬性	屬性、狀態
指令	指令	指令
活動	活動	後續回覆，通知