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

bookmark_border Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Чтобы работать с API структуры, сначала импортируйте пакет GoogleHomeSDK в свое приложение:

import GoogleHomeSDK

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

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

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

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

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

Структурный API

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

Structure представляет собой структуру на вашем домашнем графике. Он обеспечивает доступ к метаданным структуры, таким как 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!!)

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

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
}

Список API

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

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

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