API Structure su Android

È possibile accedere alle API Structure tramite le API Home per Android. 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 Gestione degli errori.

Chiamate di esempio

Visualizzare un elenco di strutture

Una volta inizializzata, una chiamata structures() restituisce un flusso di strutture a tua disposizione:

// 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 inviato un elenco valido di strutture tramite il 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à, camere e dispositivi per 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 visualizzare un elenco di camere e accedere alle relative proprietà:

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 camera con dispositivi viene eliminata, i dispositivi rimarranno nella struttura, ma non saranno più assegnati a una camera.

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 saperne di più sulle automazioni nelle API Home, consulta la Panoramica dell'API Automation su Android.

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.