Structure API ใน Android

คุณเข้าถึง 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 (อักขระ) และจะไม่มีข้อผิดพลาด นักพัฒนาแอปมีหน้าที่จัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่

การทำงานอัตโนมัติ

จุดแรกเข้าของ Automation API อยู่ในโครงสร้าง ดูข้อมูลเพิ่มเติม เกี่ยวกับการทำงานอัตโนมัติใน Home API ได้ที่ภาพรวมของ Automation API ใน Android