Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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 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 error.code y error.message para saber qué ocurrió. También puede haber códigos de suberror, por lo que debes llamar al método getSubErrorCodes() y verificar el resultado.

Cualquier excepción no controlada provocará una falla en la 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() 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 puede 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 una lista válida de estructuras pase por el 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 separada 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 habitación solo con su ID:

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

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

Una vez que tengas una estructura, puedes mover los 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 mostrará ningún error. 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.

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. En el caso de 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
            }
        }
    }
}

Grupos de dispositivos

Un grupo de dispositivos representa una colección de dispositivos definidos por el usuario dentro de una sola estructura.

Al igual que las habitaciones físicas, los grupos de dispositivos pertenecen a una sola estructura. Sin embargo, a diferencia de las habitaciones, los grupos de dispositivos son agrupaciones lógicas. Un dispositivo puede pertenecer a varios grupos de dispositivos de forma simultánea. Los grupos de dispositivos pueden contener hasta 100 dispositivos.

Los grupos de dispositivos se representan con la entidad Group, que es distinta de HomeDevice.

Crea un grupo de dispositivos

Usa GroupManagement en la estructura para crear un grupo de dispositivos:

val groupManagement = structure.trait(GroupManagementTrait)
val response = groupManagement?.createUserDefinedGroup(
  name = "Living room lights",
  memberDeviceObjectIds = listOf(light1.id.id, light2.id.id)
)

Administra la pertenencia a un grupo

Para agregar miembros a un grupo existente, sigue estos pasos:

structure.trait(GroupManagementTrait)?.addGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light3.id.id)
)

Para quitar miembros de un grupo, haz lo siguiente:

structure.trait(GroupManagementTrait)?.removeGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light1.id.id)
)

Cómo cambiar el nombre de un grupo de dispositivos

Para cambiar el nombre de un grupo de dispositivos, actualiza el atributo name en el GroupTrait del grupo:

group.trait(GroupTrait)?.update {
  name = "Movie corner"
}

Borra un grupo de dispositivos

Para borrar un grupo de dispositivos de una estructura, haz lo siguiente:

structure.trait(GroupManagementTrait)?.deleteGroup(
  groupObjectId = group.id.id
)

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.