APIs de Structure en iOS

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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 una HomeError, por lo que te recomendamos que uses un bloque do-catch para capturar HomeError en esas llamadas.

Cuando controles HomeError, revisa sus campos code y message para saber qué salió mal.

Cualquier error no controlado hará que tu app falle.

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

API de Structure

Home representa el grafo de Home 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 Home. Proporciona acceso a los metadatos de la 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 una variedad de formas de consumir sus datos:

Es posible que la llamada a structures().list() no muestre 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 impulsar la IU, se debería mostrar una lista válida de estructuras. Hay otras situaciones en las que se podría mostrar una lista de estructuras vacía, por ejemplo, si el teléfono del usuario pierde la conectividad o si revocó los permisos de tu app. Asegúrate 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 a la estructura de muestra

Cómo obtener un conjunto de estructuras

Si llamas a list() en un 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 recomendamos que uses llamadas batched() y stream() en lugar de list(), ya que estas producen datos automáticamente cuando cambia el gráfico principal.

Cómo obtener 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) ")

Busca una estructura por 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.

Cómo trabajar 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 de esa habitación 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 Room de muestra

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

Para crear una habitación nueva en un Structure, sigue estos pasos:

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 las siguientes maneras:

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 seguirá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 sala:

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

Cuando se cambia el nombre de una habitación, la estructura Room original sigue siendo la misma y el cambio se refleja en el objeto Room actualizado que se muestra.

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:

Structure tiene las siguientes APIs:

Room tiene las siguientes APIs: