คุณเข้าถึง 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")
ชื่อจะถูกตัดทอนหากเกินขีดจำกัดของ Code Point ของ Unicode (อักขระ) ที่ 60 และจะไม่มีข้อผิดพลาดเกิดขึ้น นักพัฒนาแอปมีหน้าที่จัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่
ดูประเภทอุปกรณ์ที่ผู้ใช้ให้สิทธิ์
ในระบบนิเวศของ 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
}
}
}
}
กลุ่มอุปกรณ์
กลุ่มอุปกรณ์แสดงถึงคอลเล็กชันอุปกรณ์ที่ผู้ใช้กำหนดภายในโครงสร้างเดียว
กลุ่มอุปกรณ์จะอยู่ในโครงสร้างเดียวเช่นเดียวกับห้องจริง แต่กลุ่มอุปกรณ์เป็นกลุ่มเชิงตรรกะ ซึ่งต่างจาก ห้อง อุปกรณ์เครื่องหนึ่งสามารถอยู่ในกลุ่มอุปกรณ์หลายกลุ่มพร้อมกันได้ กลุ่มอุปกรณ์มีอุปกรณ์ได้สูงสุด 100 เครื่อง
กลุ่มอุปกรณ์แสดงด้วยเอนทิตี
Group ซึ่งแตกต่างจาก HomeDevice
สร้างกลุ่มอุปกรณ์
ใช้
GroupManagement
ในโครงสร้างเพื่อสร้างกลุ่มอุปกรณ์
val groupManagement = structure.trait(GroupManagementTrait)
val response = groupManagement?.createUserDefinedGroup(
name = "Living room lights",
memberDeviceObjectIds = listOf(light1.id.id, light2.id.id)
)
จัดการการเป็นสมาชิกกลุ่ม
วิธีเพิ่มสมาชิกในกลุ่มที่มีอยู่
structure.trait(GroupManagementTrait)?.addGroupMembers(
groupObjectId = group.id.id,
memberDeviceObjectIds = listOf(light3.id.id)
)
วิธีนำสมาชิกออกจากกลุ่ม
structure.trait(GroupManagementTrait)?.removeGroupMembers(
groupObjectId = group.id.id,
memberDeviceObjectIds = listOf(light1.id.id)
)
เปลี่ยนชื่อกลุ่มอุปกรณ์
หากต้องการเปลี่ยนชื่อกลุ่มอุปกรณ์ ให้อัปเดตแอตทริบิวต์ชื่อใน GroupTrait ของกลุ่ม ดังนี้
group.trait(GroupTrait)?.update {
name = "Movie corner"
}
ลบกลุ่มอุปกรณ์
วิธีลบกลุ่มอุปกรณ์ออกจากโครงสร้าง
structure.trait(GroupManagementTrait)?.deleteGroup(
groupObjectId = group.id.id
)
การทำงานอัตโนมัติ
จุดแรกเข้าของ Automation API อยู่ในโครงสร้าง ดูข้อมูลเพิ่มเติม เกี่ยวกับการทำงานอัตโนมัติใน Home API ได้ที่ภาพรวมของ Automation API ใน Android