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 แสดงกราฟบ้านและเป็นจุดแรกเข้าของ 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> จะแสดง Set of elements ล่าสุด

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

การโทรในห้องตัวอย่าง

รับรายการห้อง

เมื่อใช้คลาส 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 struct เดิมจะยังคงเหมือนเดิม และ การเปลี่ยนแปลงจะแสดงในออบเจ็กต์ 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 รหัสระบบที่ไม่ซ้ำกันของโครงสร้างที่ห้องพักเป็นของ