APIs de Structure en Android

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 una 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 error.code y error.message para saber qué sucedió. También puede haber códigos de suberror as well, so call the getSubErrorCodes() method and check the result.

Cualquier excepción no controlada provocará que falle tu app.

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

Llamadas de muestra

Obtén una lista de estructuras

Una vez inicializada, una llamada a structures() muestra un flujo de estructuras a las 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 mostrar de inmediato una lista válida de estructuras. Si tu app es reactiva y se suscribe a ese flujo para controlar 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 el usuario revocó los permisos de tu app. Debes asegurarte de controlar estos casos en tu app.

Como alternativa, si se requiere programación imperativa en lugar de programación reactiva, se puede usar un operador de flujo terminal:

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

Esta llamada espera que una lista válida de estructuras pase por el flujo y se agota el tiempo de espera si la lista no se recibe dentro de un tiempo de espera designado por la app.

Obtén propiedades de la estructura

Con la lista de estructuras en la 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}")

Busca una estructura por 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 salas y los dispositivos de cada estructura.

Trabaja con varias estructuras

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

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 la mano, puedes obtener una lista de salas 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}")

Crea una sala

Para crear una sala nueva, haz lo siguiente:

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

Borra una sala

Como alternativa, 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 un ID:

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

Si se borra una sala con dispositivos, los dispositivos seguirán en la estructura, pero ya no estarán asignados a una sala.

Mueve dispositivos a otra sala

Una vez que tengas una estructura, puedes mover dispositivos a otra sala 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 IDs de dispositivos y salas, también puedes mover dispositivos:

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

Cambia el nombre de una sala

Llama al setName() método para cambiar el nombre de una sala:

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 arrojarán errores. Los desarrolladores son responsables de manejar nombres largos y, por ejemplo, pueden decidir si quieren informar a los usuarios que los nombres se truncarán.

Consulta los tipos de dispositivos para los que un usuario otorgó permisos

En el ecosistema de Google Home, para la mayoría de los tipos de dispositivos, los usuarios pueden otorgar permisos para todos los dispositivos de ese tipo a la vez. Para los tipos de dispositivos sensibles o restringidos, como cerraduras, cámaras o timbres, los usuarios deben otorgarles permiso de forma individual.

Para determinar si un usuario otorgó permiso para acceder a un tipo de dispositivo sensible o restringido, usa la función consentedDeviceTypes() a nivel de la estructura:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

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 Descripción general de la API de Automation en Android.