API cấu trúc trên Android

Bạn có thể truy cập vào Structure API thông qua Home API cho Android. 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

Mọi phương thức trong Home API đều có thể gửi HomeException, vì vậy, bạn nên sử dụng khối try-catch để nắm bắt 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 error.code và error.message để tìm hiểu nguyên nhân gây ra lỗi. Cũng có thể có mã lỗi phụ , vì vậy, hãy gọi phương thức getSubErrorCodes() và kiểm tra kết quả.

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 Xử lý lỗi.

Lệnh gọi mẫu

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

Sau khi được 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 luồng có thể không trả về ngay 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, một danh sách cấu trúc hợp lệ sẽ được trả về. Có những trường hợp khác mà danh sách cấu trúc trống có thể được trả về, chẳng hạn như khi đ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 đối với ứng dụng của bạn. Bạn phải đảm bảo xử lý những trường hợp này trong ứng dụng.

Ngoài ra, nếu bạn bắt buộc phải sử dụng phương thức lập trình mệnh lệnh thay vì phương thức lập trình phản ứng, thì 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 sẽ 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 không nhận được danh sách trong thời gian chờ do ứng dụng chỉ định.

Lấy các 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 chúng:

// 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 thuộc tính, 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 lấy một tham chiếu riêng cho 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ó một 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 chú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 một phòng mới:

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

Xoá phòng

Hoặc bạn có thể xoá phòng theo cách khác:

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 một phòng có thiết bị bị xoá, 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.

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

Sau khi có một 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ã nhận dạng thiết bị và 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")))

Thay đổi tên phòng

Gọi phương thức setName() để thay đổi tên phòng:

livingRoom.setName("Living Room")

Tên sẽ bị cắt ngắn nếu vượt quá giới hạn 60 điểm mã Unicode (ký tự) và sẽ không có lỗi nào được gửi. Nhà phát triển chịu trách nhiệm xử lý tên dài và có thể quyết định xem có muốn thông báo cho người dùng rằng tên sẽ bị cắt ngắn hay không.

Xem các loại thiết bị mà người dùng đã cấp quyền

Trong hệ sinh thái Google Home, đối với hầu hết các loại thiết bị, người dùng có thể cấp quyền cho tất cả các thiết bị thuộc loại đó cùng một lúc. Đối với các loại thiết bị nhạy cảm hoặc bị hạn chế, chẳng hạn như khoá, camera hoặc chuông cửa, người dùng phải cấp quyền cho từng thiết bị.

Để xác định xem người dùng đã cấp quyền truy cập vào một loại thiết bị nhạy cảm hoặc bị hạn chế hay chưa, hãy sử dụng hàm consentedDeviceTypes() ở cấp Cấu trúc:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

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 Home API, hãy xem bài viết Tổng quan về Automation API trên Android.