คุณเข้าถึง Structure API ได้ผ่าน Home API สำหรับ Android นำเข้าแพ็กเกจต่อไปนี้ไปยังแอป
import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure
การจัดการข้อผิดพลาด
เมธอดใดก็ตามใน Home API สามารถส่ง
HomeException ได้ ดังนั้นเราขอแนะนำให้คุณใช้บล็อก try-catch เพื่อ
ตรวจหา HomeException ในการเรียกทั้งหมด
เมื่อจัดการ HomeException ให้ตรวจสอบฟิลด์
error.code และ
error.message เพื่อดูว่าเกิดข้อผิดพลาดใด นอกจากนี้ อาจมีรหัสข้อผิดพลาดย่อย
ด้วย ดังนั้นให้เรียกใช้เมธอด
getSubErrorCodes() แล้วตรวจสอบผลลัพธ์
ข้อยกเว้นที่ไม่ได้จัดการจะทำให้แอปขัดข้อง
ดูข้อมูลเพิ่มเติมได้ที่ การจัดการข้อผิดพลาด
ตัวอย่างการเรียก
รับรายการโครงสร้าง
เมื่อเริ่มต้นแล้ว การเรียกใช้ 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 เป็นโฟลว์ที่อาจไม่แสดงผลรายการโครงสร้างที่ถูกต้องในทันที
หากแอปของคุณตอบสนองและสมัครใช้โฟลว์นั้นเพื่อขับเคลื่อน 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" }
จากนั้น คุณจะเข้าถึงพร็อพเพอร์ตี้ ห้อง และอุปกรณ์ของแต่ละโครงสร้างได้
ทำงานกับโครงสร้างหลายรายการ
หากต้องการใช้โครงสร้างมากกว่า 1 รายการ ให้รับการอ้างอิงแยกต่างหากสำหรับแต่ละโครงสร้าง
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!!)
นอกจากนี้ คุณยังลบห้องพักโดยใช้เพียงรหัสได้ด้วย โดยทำดังนี้
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!!))
หากมีเพียงรหัสอุปกรณ์และรหัสห้อง คุณก็ย้ายอุปกรณ์ได้เช่นกัน โดยทำดังนี้
structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))
เปลี่ยนชื่อห้อง
เรียกใช้เมธอด setName()
เพื่อเปลี่ยนชื่อห้อง
livingRoom.setName("Living Room")
ระบบจะตัดชื่อหากเกินขีดจำกัด 60 Code Point ของ Unicode (อักขระ) และจะไม่มีข้อผิดพลาด นักพัฒนาแอปมีหน้าที่จัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่
ดูประเภทอุปกรณ์ที่ผู้ใช้ให้สิทธิ์
ในระบบนิเวศของ Google Home ผู้ใช้สามารถให้สิทธิ์ สำหรับอุปกรณ์ทุกเครื่องในประเภทนั้นพร้อมกันได้สำหรับอุปกรณ์ส่วนใหญ่ สำหรับอุปกรณ์ประเภทที่มีความละเอียดอ่อนหรือถูกจำกัด เช่น ล็อก กล้อง หรือกริ่งประตู ผู้ใช้ต้องให้สิทธิ์แก่ อุปกรณ์แต่ละรายการ
หากต้องการตรวจสอบว่าผู้ใช้ได้ให้สิทธิ์เข้าถึงอุปกรณ์ประเภทที่ละเอียดอ่อนหรือ
จำกัดหรือไม่ ให้ใช้consentedDeviceTypes()
ฟังก์ชันระดับโครงสร้าง
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
}
}
}
}
การทำงานอัตโนมัติ
จุดแรกเข้าของ Automation API คือผ่านโครงสร้าง ดูข้อมูลเพิ่มเติม เกี่ยวกับการทำงานอัตโนมัติใน Home API ได้ที่ ภาพรวม Automation API ใน Android