Структурные API на iOS

Доступ к API-интерфейсам структуры можно получить через API-интерфейсы Home для iOS.

Для работы с API-интерфейсами Structure сначала импортируйте пакет GoogleHomeSDK в свое приложение:

import GoogleHomeSDK

Обработка ошибок

Некоторые методы в Home API выдают HomeError , поэтому мы рекомендуем использовать блок do-catch для перехвата HomeError при таких вызовах.

При обработке HomeError проверьте ее code и поля message , чтобы узнать, что пошло не так.

Любые необработанные ошибки приведут к сбою вашего приложения.

Более подробную информацию см. в разделе Обработка ошибок .

API структуры

Home представляет собой граф «Дома» и является точкой входа в API структур. Он предоставляет ссылки на структуры, помещения и устройства.

Structure представляет собой структуру в вашем графе Home. Она обеспечивает доступ к метаданным структуры, таким как id и name .

Используйте structures() для получения всех структур в вашем аккаунте. Структуры возвращаются в виде Query , который предлагает несколько способов использования данных:

Вызов structures().list() может не сразу возвращать допустимый набор структур. Если ваше приложение реактивное и вызывает stream() для подписки на все изменения структур для управления пользовательским интерфейсом, в конечном итоге должен быть возвращён допустимый список структур. Существуют и другие ситуации, когда может быть возвращён пустой список структур, например, если телефон пользователя теряет соединение или пользователь отозвал разрешения для вашего приложения. Обязательно обрабатывайте эти случаи в своём приложении.

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

Отсюда открывается доступ к свойствам, помещениям и устройствам каждого сооружения.

Работа с несколькими структурами

Чтобы использовать более одной структуры, получите отдельную ссылку на каждую структуру:

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

Вы также можете удалить комнату, используя ее ID:

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 .

Имена будут усечены, если их длина превышает лимит в 60 кодовых точек (символов) Unicode, без каких-либо ошибок. Разработчики несут ответственность за обработку длинных имён и, например, могут решить, следует ли уведомлять пользователей о том, что имена будут усечены.

список API

После создания экземпляра Home через него становятся доступны следующие API-интерфейсы Structure:

Structure имеет следующие API:

Room имеет следующие API: