API cấu trúc trên iOS

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

Để sử dụng Structure API, trước tiên hãy nhập gói GoogleHomeSDK vào ứng dụng của bạn:

import GoogleHomeSDK

Xử lý lỗi

Một số phương thức trong Home API sẽ gửi HomeError, vì vậy, bạn nên sử dụng khối do-catch để bắt 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 của đối tượng này để biết điều gì đã xảy ra.

Mọi lỗi chưa đượ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 đồ Home và là điểm truy cập vào Structure API. Thư viện 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 đồ Nhà của bạn. Thư viện này cung cấp quyền truy cập vào siêu dữ liệu cấu trúc, chẳng hạn 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 nhiều cách để sử dụng dữ liệu của cấu trúc này:

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 đối với ứng dụng của bạn. Bạn phải đảm bảo xử lý những trường hợp này trong ứng dụng của mình.

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

Cuộc gọi có Cấu trúc mẫu

Nhận một nhóm cấu trúc

Việc gọi list() trên một 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 các lệnh gọi batched() và stream() thay vì list(), vì các lệnh gọi này tự động tạo ra dữ liệu khi biểu đồ chính thay đổi.

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

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

// 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 cách sử dụ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ị của từng nhà.

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

Để sử dụng nhiều cấu trúc, hãy lấy một tham chiếu riêng cho 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 nhà không xoá các thiết bị trong phòng đó khỏi nhà. 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)

Ví dụ về lệnh gọi Room

Lấy danh sách phòng

Bằng cách sử dụng lớp Home, bạn có thể lấy danh sách các 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

Hoặc bạn có thể xoá phòng theo các bước sau:

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

Bạn cũng có thể xoá một phòng bằng mã nhận dạng của 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 phòng khác

Structure cũng cho phép bạn di chuyển 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 sẽ được phản ánh trong đối tượng Room được cập nhật đã trả về.

Danh sách API

Sau khi tạo một thực thể 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: