API ของโครงสร้าง

คุณเข้าถึง Structure API ได้ผ่าน Home API นําเข้าแพ็กเกจเหล่านี้ลงในแอป

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

การจัดการข้อผิดพลาด

เมธอดใดก็ตามใน Home API อาจแสดง HomeException เราจึงขอแนะนำให้คุณใช้บล็อก try-catch เพื่อจับ HomeException ในการเรียกใช้ทั้งหมด

เมื่อจัดการ HomeException ให้ตรวจสอบฟิลด์ code และ message เพื่อดูว่าเกิดข้อผิดพลาดอะไรขึ้น

ข้อยกเว้นที่ไม่ได้รับการจัดการจะทำให้แอปขัดข้อง

ดูข้อมูลเพิ่มเติมได้ที่การจัดการข้อผิดพลาด

การโทรตัวอย่าง

ดูรายการโครงสร้าง

เมื่อเริ่มต้นแล้ว การเรียก structures() จะแสดงผลลัพธ์เป็นลําดับโครงสร้างที่เข้าถึงได้ ดังนี้

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

ระบบอัตโนมัติ

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

รายการ API

เมื่อสร้างอินสแตนซ์ของ Home แล้ว คุณจะสามารถเข้าถึง Structure API ต่อไปนี้ผ่านอินสแตนซ์ดังกล่าว

เมื่อคุณมี Structure แล้ว คุณจะสามารถเข้าถึง API ต่อไปนี้ได้

นอกจากนี้ API ทั่วไปบางรายการ (เช่น devices(), id และ name) ยังมีให้บริการสำหรับ Room ด้วย