此页面由 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 是一种流程，可能不会立即返回有效的结构列表。如果您的应用是响应式应用，并订阅该流以驱动界面，则最终应返回有效的结构列表。在其他情况下，系统也可能会返回空结构列表，例如，如果用户的手机连接中断或用户撤消了对应用的权限。您应务必在应用中处理这些情况。

或者，如果强烈需要使用命令式编程（而非响应式编程），则可以使用终端流操作符：

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 和房间 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()`	列出属于该结构的所有自动化操作。系统只会返回通过 Home API 创建的自动化操作。
`createAutomation(automation)`	为结构创建自动化操作实例。
`createRoom(name)`	创建一个由用户指定名称的房间。
`deleteAutomation(automationId)`	根据 ID 删除自动化操作实例。
`deleteRoom(roomId)`	删除房间 ID 对应的房间。
`devices()`	获取结构中的所有设备。返回 `HomeObjectsFlow`。
`getAutomation(automationId)`	根据 ID 获取自动化操作实例。
`getSourceConnectivity(trait)`	获取特定 trait 的元数据。返回 `SourceConnectivity`。
`has(trait)`	检查设备是否支持当前请求的特征。
`id`	结构的唯一系统 ID。
`moveDevicesToRoom(roomId, deviceIds)`	将设备移至结构中的其他房间 ID。
`name`	结构的用户提供名称。
`rooms()`	获取结构中的所有房间。返回 `HomeObjectsFlow`。
`trait(trait)`	获取 trait 属性的当前快照。

某些常见 API（例如 devices()、id 和 name）也适用于 Room。

用户体验流程