本頁面由 Cloud Translation API 翻譯而成。

設定 API 結構

您可以透過 Home API 存取結構體 API。將這些套件匯入應用程式：

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

處理錯誤

Home API 中的任何方法都可能擲回 HomeException，因此建議您使用 try-catch 區塊，在所有呼叫中擷取 HomeException。

處理 HomeException 時，請檢查其 code 和 message 欄位，瞭解錯誤所在。

任何未處理的例外狀況都會導致應用程式停止運作。

詳情請參閱「錯誤處理」。

呼叫範例

取得結構體清單

初始化後，structures() 呼叫會傳回可供您存取的結構體資料流：

// Get a flow of all structures accessible to the user
val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allStructures: Set<Structure> = allStructuresFlow.list()

structures() API 是一種資料流，可能不會立即傳回有效的結構體清單。如果您的應用程式是回應式，且訂閱該流程以驅動 UI，則最終應會傳回有效的結構體清單。在其他情況下，系統也可能會傳回空結構體清單，例如使用者的手機連線中斷，或是使用者撤銷應用程式的權限。請務必在應用程式中處理這些情況。

或者，如果強烈要求使用命令式程式設計，而非回應式程式設計，則可以使用終端流程運算子：

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

這個呼叫會等待有效的結構體清單透過流程傳送，如果未在應用程式指定的逾時時間內收到清單，就會逾時。

取得結構體屬性

有了結構體清單，您就可以存取結構體的屬性：

// Get a flow on a structure. Flow emits new values on structure metadata changes: name.
val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

// Get structure properties
println("id ${structure.id}")
println("name ${structure.name}")

依名稱尋找結構體

如果您知道結構體的名稱，也可以使用 name 屬性存取該結構體：

val myHome = home.structures().list().first { it.name == "My home" }

在這裡，你可以存取每個結構體的屬性、房間和裝置。

使用多個結構體

如要使用多個結構，請取得每個結構的個別參照：

var structure1: Structure? = null
var structure2: Structure? = null

try {
  structure1 = home.structures().list().firstOrNull { it.name == "Main House" }
} catch (e: HomeException) {
  // Code for handling the exception
}
try {
  structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" }
} catch (e: HomeException) {
  // Code for handling the exception
}

取得房間清單

有了結構體，您就能取得房間清單，並存取房間的屬性：

val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms()
val allRooms: Set<Room> = allRoomsFlow.list()
val room: Room = allRooms.first()

println("id ${room.id}")
println("name ${room.name}")

建立聊天室

如要建立新房間，請按照下列步驟操作：

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

刪除房間

或者，你也可以刪除聊天室：

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

您也可以只使用 ID 刪除聊天室：

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

如果刪除含有裝置的房間，裝置仍會保留在結構體中，但不會再指派給任何房間。

將裝置移至其他房間

建立結構體後，你可以將裝置移至該結構體中的其他房間：

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

如果只有裝置和房間 ID，也可以移動裝置：

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

自動化動作

Automation API 的進入點是透過結構體。如要進一步瞭解 Home API 中的自動化動作，請參閱「設計自動化動作」。

API 清單

建立 Home 的執行個體後，即可透過該執行個體存取下列 Structure API：

API	說明
`structures()`	取得 Google 帳戶的所有結構體。傳回 `HomeObjectsFlow`，提供進一步的擷取和篩選選項。

取得 Structure 後，您可以透過該憑證存取下列 API：

API	說明
`automations()`	列出結構體中的所有自動化動作。系統只會傳回透過 Google Home API 建立的自動化動作。
`createAutomation(automation)`	為結構體建立自動化動作執行個體。
`createRoom(name)`	使用使用者指定的名稱建立房間。
`deleteAutomation(automationId)`	根據 ID 刪除自動化動作執行個體。
`deleteRoom(roomId)`	刪除房間 ID 對應的房間。
`devices()`	取得結構體中的所有裝置。傳回 `HomeObjectsFlow`。
`getAutomation(automationId)`	根據 ID 取得自動化動作執行個體。
`getSourceConnectivity(trait)`	取得特定特徵的中繼資料。傳回 `SourceConnectivity`。
`has(trait)`	檢查裝置是否支援目前要求的特徵。
`id`	結構體的專屬系統 ID。
`moveDevicesToRoom(roomId, deviceIds)`	將裝置移至結構體中的其他房間 ID。
`name`	使用者提供的結構體名稱。
`rooms()`	取得結構體中的所有房間。傳回 `HomeObjectsFlow`。
`trait(trait)`	取得特徵屬性的目前快照。

部分常見的 API (例如 devices()、id 和 name) 也適用於 Room。

使用者體驗流程

Device API