API cấu trúc

Bạn có thể truy cập vào API cấu trúc thông qua API Home. Nhập các gói này vào ứng dụng:

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

Xử lý lỗi

Bất kỳ phương thức nào trong API Home đều có thể gửi một HomeException, vì vậy, bạn nên sử dụng khối try-catch để phát hiện HomeException trên tất cả các lệnh gọi.

Khi xử lý HomeException, hãy kiểm tra các trường code và message để tìm hiểu xem đã xảy ra lỗi gì.

Mọi ngoại lệ chưa được xử lý sẽ khiến ứng dụng của bạn gặp sự cố.

Để biết thêm thông tin, hãy xem phần Xử lý lỗi.

Lệnh gọi mẫu

Lấy danh sách cấu trúc

Sau khi khởi chạy, lệnh gọi structures() sẽ trả về một Luồng cấu trúc mà bạn có thể truy cập:

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

API structures() là một flow có thể không trả về ngay một danh sách cấu trúc hợp lệ. Nếu ứng dụng của bạn có tính phản ứng và đăng ký luồng đó để điều khiển giao diện người dùng, thì cuối cùng, hệ thống sẽ trả về một danh sách cấu trúc hợp lệ. Có những trường hợp khác mà danh sách cấu trúc trống có thể được trả về, ví dụ: nếu điện thoại của người dùng mất kết nối hoặc nếu người dùng đã thu hồi quyền cho ứng dụng của bạn. Bạn phải nhớ xử lý những trường hợp này trong ứng dụng.

Ngoài ra, nếu bạn cần lập trình mệnh lệnh thay vì lập trình phản ứng, bạn có thể sử dụng toán tử luồng đầu cuối:

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

Lệnh gọi này chờ một danh sách cấu trúc hợp lệ đi qua luồng và hết thời gian chờ nếu danh sách không được nhận trong thời gian chờ do ứng dụng chỉ định.

Lấy thuộc tính cấu trúc

Khi có danh sách cấu trúc, bạn có thể truy cập vào các thuộc tính của các cấu trúc đó:

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

Tìm cấu trúc theo tên

Nếu biết tên của một cấu trúc, bạn cũng có thể truy cập vào cấu trúc đó bằng thuộc tính name:

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

Từ đó, bạn có thể truy cập vào các tài sản, phòng và thiết bị cho từng cấu trúc.

Làm việc với nhiều cấu trúc

Để sử dụng nhiều cấu trúc, hãy tham chiếu riêng đến từng cấu trúc:

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
}

Lấy danh sách phòng

Khi có cấu trúc, bạn có thể lấy danh sách phòng và truy cập vào các thuộc tính của phòng:

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

Tạo một phòng

Cách tạo phòng mới:

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

Xoá phòng

Ngoài ra, bạn có thể xoá phòng theo cách sau:

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

Bạn cũng có thể xoá phòng chỉ bằng mã nhận dạng:

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

Nếu bạn xoá một phòng có thiết bị, thì các thiết bị đó vẫn sẽ nằm trong cấu trúc nhưng không còn được chỉ định cho phòng nào nữa.

Chuyển thiết bị sang một phòng khác

Sau khi có cấu trúc, bạn có thể di chuyển thiết bị sang một phòng khác trong cấu trúc đó:

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

Nếu chỉ có mã thiết bị và mã phòng, bạn cũng có thể di chuyển thiết bị:

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

Chế độ tự động hoá

Điểm truy cập vào Automation API là thông qua một cấu trúc. Để tìm hiểu thêm về tính năng Tự động hoá trong API Home, hãy xem bài viết Thiết kế tính năng tự động hoá.

Danh sách API

Sau khi tạo một thực thể của Home, bạn có thể truy cập vào các API Cấu trúc sau thông qua thực thể đó:

Sau khi có Structure, bạn có thể truy cập các API sau thông qua API đó:

Một số API phổ biến (chẳng hạn như devices(), id và name) cũng có sẵn cho Room.