Se puede acceder a las APIs de Structure a través de las APIs de Home para Android. Importa estos paquetes a tu app:
import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure
Manejo de errores
Cualquier método de las APIs de Home puede arrojar un HomeException
, por lo que te recomendamos que uses un bloque try-catch
para detectar HomeException
en todas las llamadas.
Cuando manejes HomeException
, verifica sus campos code
y message
para saber qué ocurrió.
Cualquier excepción no controlada provocará una falla en la app.
Para obtener más información, consulta Control de errores.
Llamadas de muestra
Obtén una lista de estructuras
Una vez inicializada, una llamada a structures()
devuelve un flujo de estructuras al que puedes acceder:
// Get a flow of all structures accessible to the user val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures() // Calling list() on a HomeObjectsFlow returns the first Set of elements. val allStructures: Set<Structure> = allStructuresFlow.list()
La API de structures()
es un flujo que podría no devolver de inmediato una lista válida de estructuras. Si tu app es reactiva y se suscribe a ese flujo 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.
Como alternativa, si se requiere imperativamente la programación imperativa en lugar de la programación reactiva, se puede usar un operador de flujo terminal:
val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }
Esta llamada espera a que llegue una lista válida de estructuras a través del flujo y se agota el tiempo de espera si no se recibe la lista dentro del tiempo de espera designado por la app.
Obtén propiedades de la estructura
Con la lista de estructuras en mano, puedes acceder a sus propiedades:
// Get a flow on a structure. Flow emits new values on structure metadata changes: name. val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId) // Get a snapshot of the structure. val structure: Structure = structureFlow.first() // Get structure properties println("id ${structure.id}") println("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
:
val myHome = home.structures().list().first { it.name == "My home" }
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? = null var structure2: Structure? = null try { structure1 = home.structures().list().firstOrNull { it.name == "Main House" } } catch (e: HomeException) { // Code for handling the exception } try { structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" } } catch (e: HomeException) { // Code for handling the exception }
Obtén una lista de salas
Con una estructura en mano, puedes obtener una lista de habitaciones y acceder a sus propiedades:
val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms() val allRooms: Set<Room> = allRoomsFlow.list() val room: Room = allRooms.first() println("id ${room.id}") println("name ${room.name}")
Crear una sala
Para crear una habitación nueva, sigue estos pasos:
val testName = "Test Room Name" val newRoom: Room = structure.createRoom(testName)
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 solo con su ID:
val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull() structure.deleteRoom(roomToDelete1!!)
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
Una vez que tengas una estructura, puedes mover dispositivos a otra habitación dentro de esa estructura:
val room2 = structure.rooms().get(Id("room_id_other_structure")) val device1 = structure.devices().get(Id("device_id1")) structure.moveDevicesToRoom(room2!!, listOf(device1!!))
Si solo tienes los IDs de los dispositivos y las habitaciones, también puedes mover los dispositivos:
structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))
Cómo cambiar el nombre de una habitación
Llama al método setName()
para cambiar el nombre de una habitación:
livingRoom.setName("Living Room")
Los nombres se truncarán si superan el límite de 60 puntos de código Unicode (caracteres) y no se generarán errores. Los desarrolladores son responsables de controlar los nombres largos y, por ejemplo, pueden decidir si quieren informar a los usuarios que los nombres se truncarán.
Automatizaciones
El punto de entrada a la API de Automation es a través de una estructura. Para obtener más información sobre las automatizaciones en las APIs de Home, consulta la Descripción general de la API de Automation en Android.
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:
API | Descripción |
---|---|
structures() |
Obtiene todas las estructuras de la Cuenta de Google. Devuelve un HomeObjectsFlow que proporciona más opciones de recuperación y filtrado. |
Una vez que tengas un objeto Structure
, podrás acceder a las siguientes APIs a través de él:
API | Descripción |
---|---|
automations() |
Enumera todas las automatizaciones que pertenecen a la estructura. Solo se muestran las automatizaciones creadas a través de las APIs de Home. |
createAutomation(automation) |
Crea una instancia de automatización para una estructura. |
createRoom(name) |
Crea una sala con el nombre que proporciona el usuario. |
deleteAutomation(automationId) |
Borra una instancia de automatización por su ID. |
deleteRoom(roomId) |
Borra una sala con el ID de la sala. |
devices() |
Obtiene todos los dispositivos de la estructura. Muestra un HomeObjectsFlow . |
getAutomation(automationId) |
Obtiene una instancia de automatización por su ID. |
getSourceConnectivity(trait) |
Obtiene los metadatos de un rasgo en particular. Muestra un SourceConnectivity . |
has(trait) |
Comprueba si el dispositivo admite el rasgo solicitado actual. |
id |
Es el ID único del sistema de la estructura. |
moveDevicesToRoom(roomId, deviceIds) |
Mueve los dispositivos a un ID de habitación diferente en la estructura. |
name |
Es el nombre de la estructura proporcionado por el usuario. |
rooms() |
Obtiene todas las habitaciones de la estructura. Muestra un HomeObjectsFlow . |
trait(trait) |
Obtén una instantánea actual de los atributos del rasgo. |
Algunas APIs comunes (como devices()
, id
y name
) también están disponibles para un Room
.