Structure API ใน iOS

คุณเข้าถึง Structure API ได้ผ่าน Home API สำหรับ iOS

หากต้องการใช้งาน Structure API ให้นําเข้าแพ็กเกจ GoogleHomeSDK ลงในแอปก่อน โดยทําดังนี้

import GoogleHomeSDK

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

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

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

ข้อผิดพลาดที่ไม่ได้รับการจัดการจะทำให้แอปขัดข้อง

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

Structure API

Home แสดงกราฟ Home และเป็นจุดแรกเข้าของ Structure API ซึ่งจะระบุข้อมูลอ้างอิงสำหรับโครงสร้าง ห้อง และอุปกรณ์

Structure แสดงโครงสร้างในกราฟหน้าแรก ซึ่งจะให้สิทธิ์เข้าถึงข้อมูลเมตาโครงสร้าง เช่น id และ name

ใช้ structures() เพื่อรับโครงสร้างทั้งหมดในบัญชี ระบบจะแสดงโครงสร้างในรูปแบบ Query ซึ่งจะมีตัวเลือกวิธีใช้ข้อมูลดังนี้

API คำอธิบาย
stream() แสดงผล Publisher ที่ส่งออกแต่ละออบเจ็กต์แยกกันเมื่อมีการเปลี่ยนแปลง
batched() แสดงผล Publisher ที่แสดงผลลัพธ์ปัจจุบันเป็น Set ของออบเจ็กต์ Set ที่ส่งออกแต่ละรายการแสดงสถานะปัจจุบันของกราฟออบเจ็กต์
list() แสดงผลลัพธ์ปัจจุบันเป็น Set ของออบเจ็กต์

การเรียกใช้ structures().list() อาจไม่แสดงชุดโครงสร้างที่ถูกต้องในทันที หากแอปของคุณเป็นแบบเรียลไทม์และเรียกใช้ stream() เพื่อติดตามการเปลี่ยนแปลงโครงสร้างทั้งหมดเพื่อขับเคลื่อน UI ระบบจะแสดงรายการโครงสร้างที่ถูกต้องในท้ายที่สุด นอกจากนี้ยังมีสถานการณ์อื่นๆ ที่ระบบอาจแสดงรายการโครงสร้างว่าง เช่น หากโทรศัพท์ของผู้ใช้ขาดการเชื่อมต่อ หรือหากผู้ใช้เพิกถอนสิทธิ์เข้าถึงแอปของคุณ คุณควรจัดการกับกรณีเหล่านี้ในแอป

@Published public private(set) var structures: [Structure] = []
private var structuresCancellable: AnyCancellable?

  self.structuresCancellable = home
    .structures()
    .batched()
    .receive(on: DispatchQueue.main)
    .map { Array($0) }
    .catch {
      Logger.error("Failed to load structures: \($0)")
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

ตัวอย่างการเรียกใช้โครงสร้าง

รับชุดโครงสร้าง

การเรียกใช้ list() ใน Query<Structure> จะแสดงชุดองค์ประกอบล่าสุด ดังนี้

// Get a stream of all structures accessible to the user
let allStructuresChanges = try await self.home.structures()
let allStructures = try? await allStructuresChanges.list()

เมื่อออกแบบแอปแบบเรียลไทม์ คุณควรใช้การเรียกใช้ batched() และ stream() แทน list() เนื่องจากจะสร้างข้อมูลโดยอัตโนมัติเมื่อกราฟหน้าแรกมีการเปลี่ยนแปลง

รับพร็อพเพอร์ตี้โครงสร้าง

เมื่อมีรายการโครงสร้างแล้ว คุณจะเข้าถึงพร็อพเพอร์ตี้ของโครงสร้างได้ดังนี้

// Get a stream of changes taking place on a structure.
let structureChanges = try await home.structures().list().filter { $0.id == structureID }

// Get a snapshot of the structure.
let structure = try await structureChanges.first!

// Get structure properties
print("id \(structure.id) ")
print("name \(structure.name) ")

ค้นหาโครงสร้างตามชื่อ

หากทราบชื่อโครงสร้าง คุณจะเข้าถึงโครงสร้างนั้นได้โดยใช้พร็อพเพอร์ตี้ name ดังนี้

do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let error as HomeError {
  // Code for handling the exception
}

จากตรงนั้น คุณจะเข้าถึงที่พัก ห้อง และอุปกรณ์ของแต่ละโครงสร้างได้

ทำงานกับโครงสร้างหลายรายการ

หากต้องการใช้โครงสร้างมากกว่า 1 รายการ ให้รับการอ้างอิงแยกกันสำหรับแต่ละโครงสร้าง ดังนี้

var structure1: Structure!
var structure2: Structure!
do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let error as HomeError {
  // Code for handling the exception
}
do {
  structure2 = try await home.structures().list().first(where: { $0.name == "Guest Cottage" })
} catch let error as HomeError {
  // Code for handling the exception
}

ห้องพัก

ห้องประกอบด้วยกลุ่มอุปกรณ์ ห้องเป็นส่วนหนึ่งของโครงสร้างเสมอ และโครงสร้างอาจมีห้องหลายห้อง การนำห้องออกจากโครงสร้างจะไม่นำอุปกรณ์ในห้องนั้นออกจากโครงสร้าง อย่างไรก็ตาม หากลบห้องออก ระบบจะยกเลิกการกำหนดอุปกรณ์ในห้องนั้น

ใช้ Home.rooms() เพื่อเรียกข้อมูลห้องทั้งหมดในบัญชี จากนั้นใช้ roomID = device.roomID เพื่อแสดงอุปกรณ์ที่เกี่ยวข้องในแต่ละห้อง

self.home.rooms().batched()
  .combineLatest(self.home.devices().batched())
  .receive(on: DispatchQueue.main)
  .catch { error in
    Logger.error("Failed to load rooms and devices: \(error)")
    return Just((Set<Room>(), Set<HomeDevice>()))
  }
  .map { rooms, devices in
    var devicesByRoom = [Room: [HomeDevice]]()
    for room in rooms where room.structureID == currentStructureID {
      devicesByRoom[room] = devices.filter { $0.roomID == room.id }
    }
    return devicesByRoom
  }.assign(to: &self.$devicesByRoom)

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

ดูรายการห้อง

เมื่อใช้คลาส Home คุณจะดูรายการห้องและเข้าถึงพร็อพเพอร์ตี้ของห้องเหล่านั้นได้ ดังนี้

let allRoomsChanges = self.home.rooms()
let allRooms = try await allRoomsChanges.list()
let room = allRooms.first!
XCTAssertTrue(allRooms.contains(room))

print("id \(room.id) ")
print("name \(room.name) ")

สร้างห้องแชท

วิธีสร้างห้องใหม่ใน Structure

let testName = "Test Room Name"
var newRoom: Room!
do {
  newRoom = try await structure.createRoom(name: testName)
  XCTAssertNotNil(newRoom)
} catch let error as HomeError {
  // Code for handling the exception
}

ลบห้อง

หรือจะลบห้องแชทก็ได้โดยทำดังนี้

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

นอกจากนี้ คุณยังลบห้องพักโดยใช้รหัสได้ด้วย โดยทำดังนี้

let roomToDelete = allRooms.first(where: { $0.id == room.id })
if let roomToDelete1 = roomToDelete {
  do {
    try await structure.deleteRoom(roomToDelete1)
  } catch let error as HomeError {
    // Code for handling the exception
  }
}

หากลบห้องที่มีอุปกรณ์ออก อุปกรณ์จะยังคงอยู่ในโครงสร้าง แต่จะไม่ได้กำหนดให้กับห้องอีกต่อไป

ย้ายอุปกรณ์ไปห้องอื่น

Structure ยังช่วยให้คุณย้ายอุปกรณ์ไปห้องอื่นได้ด้วย โดยทำดังนี้

do {
  try await structure.move(device: light, to: room)
} catch let error as HomeError {
  // Code for handling the exception
}

เปลี่ยนชื่อห้อง

เรียกใช้วิธีต่อไปนี้ของ setName(_:) เพื่อเปลี่ยนชื่อห้อง

let updatedRoom = try await theRoom.setName("new room name")

เมื่อเปลี่ยนชื่อห้อง โครงสร้าง Room เดิมจะยังคงเหมือนเดิม และการเปลี่ยนแปลงจะแสดงในออบเจ็กต์ Room ที่อัปเดตแล้วซึ่งแสดงผล

รายการ API

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

API คำอธิบาย
devices() ดูอุปกรณ์ทั้งหมดที่บัญชีนี้มองเห็น
device(id:) รับ Publisher สำหรับอุปกรณ์ที่ระบุซึ่งส่งสถานะปัจจุบันและอีกครั้งเมื่อมีการอัปเดตสถานะในอนาคต
structures() รับโครงสร้างทั้งหมดในบัญชี Google แสดงผล Query<Structure> ที่มีตัวเลือกการดึงข้อมูลและการกรองเพิ่มเติม
structure(id:) รับโครงสร้างที่มีรหัสที่ตรงกัน
rooms() รับห้องทั้งหมดในบัญชี Google แสดงผล Query<strRoom> ที่มีตัวเลือกการดึงข้อมูลและการกรองเพิ่มเติม
room(id:) รับ Publisher สำหรับห้องที่ระบุซึ่งแสดงสถานะปัจจุบันและแสดงอีกครั้งเมื่อมีการอัปเดตสถานะในอนาคต

Structure มี API ต่อไปนี้

API คำอธิบาย
deleteRoom(id:) ลบห้องด้วยรหัสห้อง
id รหัสระบบที่ไม่ซ้ำกันของโครงสร้าง
move(device:, to:) ย้ายอุปกรณ์ไปไว้ในห้องอื่นในโครงสร้าง
move(device:, to:) ย้ายอุปกรณ์ที่มีรหัสที่ระบุไปยังห้องที่มีรหัสที่ระบุ
move(devices:, to:) ย้ายอุปกรณ์ที่ระบุไปยังห้องที่ระบุ
move(devices:, to:) ย้ายอุปกรณ์ที่มีรหัสที่ระบุไปยังห้องที่มีรหัสที่ระบุ
name ชื่อโครงสร้างที่ผู้ใช้ระบุ

Room มี API ต่อไปนี้

API คำอธิบาย
id รหัสระบบที่ไม่ซ้ำกันของห้องพัก
name ชื่อห้องที่ผู้ใช้ระบุ
structureID รหัสระบบที่ไม่ซ้ำกันของโครงสร้างที่ห้องพักอยู่