APIs de Structure en iOS

Se puede acceder a las APIs de Structure a través de las APIs de Home para iOS.

Para trabajar con las APIs de Structure, primero importa el paquete GoogleHomeSDK a tu app:

import GoogleHomeSDK

Manejo de errores

Algunos métodos de las APIs de Home arrojan un HomeError, por lo que te recomendamos que uses un bloque do-catch para detectar HomeError en esas llamadas.

Cuando manejes HomeError, verifica sus campos code y message para saber qué ocurrió.

Cualquier error no controlado provocará que falle la app.

Para obtener más información, consulta Control de errores.

API de Structure

Home representa el grafo de la casa y es el punto de entrada a la API de Structure. Proporciona referencias a estructuras, habitaciones y dispositivos.

Structure representa una estructura en tu grafo de la casa. Proporciona acceso a metadatos de estructura, como id y name.

Usa structures() para obtener todas las estructuras de tu cuenta. Las estructuras se devuelven en forma de un Query, que ofrece varias formas de consumir sus datos:

Es posible que la llamada a structures().list() no devuelva de inmediato un conjunto válido de estructuras. Si tu app es reactiva y llama a stream() para suscribirse a todos los cambios de estructura para controlar la IU, eventualmente se debería devolver una lista válida de estructuras. Hay otras situaciones en las que se podría devolver una lista de estructura vacía, por ejemplo, si el teléfono del usuario pierde la conectividad o si el usuario revocó los permisos de tu app. Debes asegurarte de controlar estos casos en tu app.

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

Llamadas de Sample Structure

Obtén un conjunto de estructuras

Si se llama a list() en un objeto Query<Structure>, se muestra el conjunto de elementos más reciente:

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

Cuando diseñes una app reactiva, te convendrá usar llamadas a batched() y stream() en lugar de list(), ya que estas producen datos automáticamente cuando cambia el gráfico principal.

Obtén propiedades de la estructura

Con la lista de estructuras en mano, puedes acceder a sus propiedades:

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

Cómo encontrar una estructura por su nombre

Si conoces el nombre de una estructura, también puedes acceder a ella con la propiedad name:

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

Desde allí, se puede acceder a las propiedades, las habitaciones y los dispositivos de cada estructura.

Trabaja con varias estructuras

Para usar más de una estructura, obtén una referencia independiente para cada una:

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
}

Habitaciones

Una habitación contiene un grupo de dispositivos. Una habitación siempre forma parte de una estructura, y una estructura puede tener varias habitaciones. Quitar una habitación de una estructura no quita los dispositivos de esa habitación de la estructura. Sin embargo, si se borra la habitación, los dispositivos que se encuentren en ella dejarán de estar asignados.

Usa Home.rooms() para recuperar todas las habitaciones de la cuenta y, luego, usa roomID = device.roomID para mostrar los dispositivos correspondientes en cada habitación.

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)

Llamadas de muestra de Room

Obtén una lista de salas

Con la clase Home, puedes obtener una lista de salas y acceder a sus propiedades:

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

Crear una sala

Sigue estos pasos para crear una habitación nueva en un 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
}

Cómo borrar una habitación

También puedes borrar una sala de la siguiente manera:

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

También puedes borrar una sala con su 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
  }
}

Si se borra una habitación con dispositivos, estos permanecerán en la estructura, pero ya no estarán asignados a una habitación.

Cómo mover dispositivos a otra habitación

Structure también te permite mover un dispositivo a otra habitación:

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

Cómo cambiar el nombre de una habitación

Llama al método setName(_:) para cambiar el nombre de una habitación:

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

Cuando se cambia el nombre de una habitación, la struct Room original permanece igual y el cambio se refleja en el objeto Room actualizado que se devuelve.

Lista de APIs

Una vez que se crea una instancia de Home, se puede acceder a las siguientes APIs de Structure a través de ella:

La Structure tiene las siguientes APIs:

Room tiene las siguientes APIs: