此页面由 Cloud Translation API 翻译。

Android 上的 Structure API

可通过适用于 Android 的 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() 调用会返回一个可供您访问的结构 Flow：

// 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")))

更改会议室名称

调用 setName() 方法来更改房间的名称：

livingRoom.setName("Living Room")

如果名称超过 60 个 Unicode 码位（字符）的限制，系统会截断名称，但不会抛出任何错误。开发者负责处理过长的名称，例如，可以决定是否要告知用户名称将被截断。

自动化操作

Automation API 的入口点是通过结构实现的。如需详细了解 Home API 中的自动化，请参阅 Android 上的 Automation 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)`	获取特定特征的元数据。返回 `SourceConnectivity`。
`has(trait)`	检查设备是否支持当前请求的特征。
`id`	结构的唯一系统 ID。
`moveDevicesToRoom(roomId, deviceIds)`	将设备移至结构中的其他房间 ID。
`name`	用户提供的结构的名称。
`rooms()`	获取结构中的所有房间。返回 `HomeObjectsFlow`。
`trait(trait)`	获取特征属性的当前快照。

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