Estruturar APIs

As APIs Structure podem ser acessadas pelas APIs Home. Importe estes pacotes para o app:

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

Tratamento de erros

Qualquer método nas APIs Home pode gerar uma HomeException. Por isso, recomendamos usar um bloco try-catch para capturar HomeException em todas as chamadas.

Ao processar HomeException, verifique os campos code e message para saber o que deu errado.

Qualquer exceção não processada vai resultar em falha no app.

Para mais informações, consulte Como tratar erros.

Exemplos de chamadas

Receber uma lista de estruturas

Depois de inicializada, uma chamada structures() retorna um fluxo de estruturas acessível a você:

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

A API structures() é um fluxo que pode não retornar imediatamente uma lista válida de estruturas. Se o app for reativo e se inscrever nesse fluxo para controlar a interface, uma lista válida de estruturas será retornada. Há outras situações em que uma lista de estrutura vazia pode ser retornada, por exemplo, se o telefone do usuário perder a conectividade ou se o usuário revogou as permissões para o app. É necessário processar esses casos no app.

Como alternativa, se a programação imperativa for fortemente necessária em vez da programação reativa, um operador de fluxo terminal poderá ser usado:

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

Essa chamada aguarda uma lista válida de estruturas para passar pelo fluxo e expira se a lista não for recebida dentro de um tempo limite designado pelo app.

Acessar propriedades da estrutura

Com a lista de estruturas em mãos, é possível acessar as propriedades delas:

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

Encontrar uma estrutura por nome

Se você souber o nome de uma estrutura, também poderá acessá-la usando a propriedade name:

val myHome = home.structures().list().first { it.name == "My home" }

A partir daí, é possível acessar as propriedades, os cômodos e os dispositivos de cada estrutura.

Trabalhar com várias estruturas

Para usar mais de uma estrutura, receba uma referência separada para cada uma delas:

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
}

Receber uma lista de salas

Com uma estrutura em mãos, você pode acessar uma lista de salas e as propriedades delas:

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

Criar uma sala

Para criar um novo ambiente:

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

Excluir um ambiente

Também é possível excluir um ambiente:

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

Também é possível excluir uma sala com apenas um ID:

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

Se um ambiente com dispositivos for excluído, os dispositivos ainda estarão na estrutura, mas não serão mais atribuídos a um ambiente.

Mover dispositivos para outro ambiente

Depois de criar uma estrutura, você pode mover dispositivos para um ambiente diferente nesta estrutura:

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

Se você tiver apenas os IDs de dispositivo e de cômodo, também poderá mover dispositivos:

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

Automações

O ponto de entrada da API Automation é por uma estrutura. Para saber mais sobre automações nas APIs Home, consulte Criar uma automação.

Lista de APIs

Depois que uma instância de Home é criada, as seguintes APIs Structure ficam acessíveis:

Depois de ter um Structure, as seguintes APIs podem ser acessadas:

Algumas APIs comuns (como devices(), id e name) também estão disponíveis para um Room.