API cấu trúc trên iOS

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Bạn có thể truy cập vào API cấu trúc thông qua API Home cho iOS.

Để làm việc với các API Cấu trúc, trước tiên, hãy nhập gói GoogleHomeSDK vào ứng dụng:

import GoogleHomeSDK

Xử lý lỗi

Một số phương thức trong API Home sẽ gửi một HomeError, vì vậy, bạn nên sử dụng khối do-catch để phát hiện HomeError trên các lệnh gọi đó.

Khi xử lý HomeError, hãy kiểm tra các trường code và message để tìm hiểu xem đã xảy ra lỗi gì.

Mọi lỗi không được xử lý sẽ khiến ứng dụng của bạn gặp sự cố.

Để biết thêm thông tin, hãy xem phần Xử lý lỗi.

Structure API

Home đại diện cho biểu đồ Trang chủ và là điểm truy cập vào API Cấu trúc. Tệp này cung cấp thông tin tham chiếu đến các cấu trúc, phòng và thiết bị.

Structure đại diện cho một cấu trúc trong biểu đồ Trang chủ. Thư viện này cung cấp quyền truy cập vào siêu dữ liệu cấu trúc như id và name.

Sử dụng structures() để lấy tất cả cấu trúc trong tài khoản của bạn. Các cấu trúc được trả về dưới dạng Query, cung cấp một số cách sử dụng dữ liệu của cấu trúc:

Lệnh gọi structures().list() có thể không trả về ngay một tập hợp cấu trúc hợp lệ. Nếu ứng dụng của bạn có tính phản ứng và gọi stream() để đăng ký tất cả các thay đổi về cấu trúc nhằm điều khiển giao diện người dùng, thì cuối cùng, một danh sách cấu trúc hợp lệ sẽ được trả về. Có những trường hợp khác mà danh sách cấu trúc trống có thể được trả về, chẳng hạn như nếu điện thoại của người dùng mất kết nối hoặc nếu người dùng đã thu hồi quyền cho ứng dụng của bạn. Bạn phải nhớ xử lý những trường hợp này trong ứng dụng.

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

Lệnh gọi Cấu trúc mẫu

Nhận một tập hợp cấu trúc

Việc gọi list() trên Query<Structure> sẽ trả về Tập hợp các phần tử gần đây nhất:

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

Khi thiết kế một ứng dụng phản ứng, bạn nên sử dụng lệnh gọi batched() và stream() thay vì list(), vì các lệnh gọi này sẽ tự động tạo dữ liệu khi biểu đồ trang chủ thay đổi.

Lấy thuộc tính cấu trúc

Khi có danh sách cấu trúc, bạn có thể truy cập vào các thuộc tính của các cấu trúc đó:

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

Tìm cấu trúc theo tên

Nếu biết tên của một cấu trúc, bạn cũng có thể truy cập vào cấu trúc đó bằng thuộc tính name:

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

Từ đó, bạn có thể truy cập vào các tài sản, phòng và thiết bị cho từng cấu trúc.

Làm việc với nhiều cấu trúc

Để sử dụng nhiều cấu trúc, hãy tham chiếu riêng đến từng cấu trúc:

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
}

Rooms

Một phòng chứa một nhóm thiết bị. Một phòng luôn là một phần của cấu trúc và một cấu trúc có thể có nhiều phòng. Việc xoá một phòng khỏi cấu trúc sẽ không xoá các thiết bị trong phòng đó khỏi cấu trúc. Tuy nhiên, nếu phòng đó bị xoá, các thiết bị trong phòng đó sẽ không được chỉ định.

Sử dụng Home.rooms() để truy xuất tất cả các phòng trong tài khoản, sau đó sử dụng roomID = device.roomID để hiển thị các thiết bị tương ứng trong mỗi phòng.

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)

Lệnh gọi Room mẫu

Lấy danh sách phòng

Khi sử dụng lớp Home, bạn có thể lấy danh sách phòng và truy cập vào các thuộc tính của các phòng đó:

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

Tạo một phòng

Cách tạo phòng mới trong 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
}

Xoá phòng

Ngoài ra, bạn có thể xoá phòng theo cách sau:

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

Bạn cũng có thể xoá phòng bằng mã phòng:

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
  }
}

Nếu bạn xoá một phòng có thiết bị, thì các thiết bị đó vẫn sẽ nằm trong cấu trúc nhưng không còn được chỉ định cho phòng nào nữa.

Chuyển thiết bị sang một phòng khác

Structure cũng cho phép bạn di chuyển một thiết bị sang một phòng khác:

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

Thay đổi tên phòng

Gọi phương thức setName(_:) để thay đổi tên của một phòng:

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

Khi thay đổi tên của một phòng, cấu trúc Room ban đầu vẫn giữ nguyên và thay đổi được phản ánh trong đối tượng Room đã cập nhật được trả về.

Danh sách API

Sau khi tạo một thực thể của Home, bạn có thể truy cập vào các API Cấu trúc sau thông qua thực thể đó:

Structure có các API sau:

Room có các API sau: