API per la struttura

È possibile accedere alle API Structure tramite le API Home. Importa questi pacchetti nella tua app:

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

Gestione degli errori

Qualsiasi metodo nelle API Home può generare un HomeException, pertanto ti consigliamo di utilizzare un blocco try-catch per intercettare HomeException in tutte le chiamate.

Quando gestisci HomeException, controlla i campi code e message per scoprire cosa è andato storto.

Eventuali eccezioni non gestite causeranno l'arresto anomalo dell'app.

Per ulteriori informazioni, consulta la sezione Gestione degli errori.

Chiamate di esempio

Ottenere un elenco di strutture

Una volta inizializzata, una chiamata structures() restituisce un flusso di strutture a cui hai accesso:

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

L'API structures() è un flusso che potrebbe non restituire immediatamente un elenco valido di strutture. Se la tua app è reattiva e si iscrive a questo flusso per gestire l'interfaccia utente, dovrebbe essere restituito un elenco valido di strutture. Esistono altre situazioni in cui potrebbe essere restituito un elenco di strutture vuoto, ad esempio se lo smartphone dell'utente perde la connettività o se l'utente ha revocato le autorizzazioni per la tua app. Assicurati di gestire questi casi nella tua app.

In alternativa, se è fortemente richiesta la programmazione imperativa anziché la programmazione reattiva, è possibile utilizzare un operatore di flusso terminale:

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

Questa chiamata attende che venga visualizzato un elenco valido di strutture nel flusso e scade se l'elenco non viene ricevuto entro un timeout specificato dall'app.

Recupera le proprietà della struttura

Una volta ottenuto l'elenco delle strutture, puoi accedere alle relative proprietà:

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

Trovare una struttura per nome

Se conosci il nome di una struttura, puoi accedervi anche utilizzando la proprietà name:

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

Da qui, puoi accedere a proprietà, stanze e dispositivi di ogni struttura.

Lavorare con più strutture

Per utilizzare più di una struttura, ottieni un riferimento separato per ogni struttura:

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
}

Ottenere un elenco di stanze

Una volta scelta una struttura, puoi ottenere un elenco di stanze e accedere alle proprietà per loro:

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 stanza virtuale

Per creare una nuova stanza:

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

Eliminare una stanza

In alternativa, puoi eliminare una stanza:

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

Puoi anche eliminare una stanza solo con un ID:

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

Se una stanza con dispositivi viene eliminata, i dispositivi rimarranno nella struttura, ma non saranno più assegnati a una stanza.

Spostare i dispositivi in un'altra stanza

Una volta creata una casa, puoi spostare i dispositivi in un'altra stanza all'interno della casa:

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

Se hai solo gli ID dispositivo e stanza, puoi anche spostare i dispositivi:

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

Automazioni

Il punto di contatto dell'API Automation è una struttura. Per scoprire di più sulle automazioni nelle API Home, consulta Creare un'automazione.

elenco delle API

Una volta creata un'istanza di Home, tramite questa sono accessibili le seguenti API Structure:

Una volta ottenuto un Structure, potrai accedere alle seguenti API:

Alcune API comuni (ad esempio devices(), id e name) sono disponibili anche per un Room.