Gebäude-APIs unter Android

Auf die Structure APIs kann über die Home APIs für Android zugegriffen werden. Importieren Sie diese Pakete in Ihre App:

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

Fehlerbehandlung

Jede Methode in den Home APIs kann eine HomeException auslösen. Wir empfehlen daher, einen try-catch-Block zu verwenden, um HomeException bei allen Aufrufen abzufangen.

Prüfen Sie beim Verarbeiten von HomeException die Felder code und message, um herauszufinden, was schiefgelaufen ist.

Nicht abgefangene Ausnahmen führen zum Absturz Ihrer App.

Weitere Informationen finden Sie unter Fehlerbehandlung.

Beispielanrufe

Liste der Gebäude abrufen

Nach der Initialisierung gibt ein structures()-Aufruf einen Flow von Strukturen zurück, auf die Sie zugreifen können:

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

Die structures() API ist ein Ablauf, der möglicherweise nicht sofort eine gültige Liste von Gebäuden zurückgibt. Wenn Ihre App reaktiv ist und diesen Flow abonniert, um die Benutzeroberfläche zu steuern, sollte schließlich eine gültige Liste von Strukturen zurückgegeben werden. Es gibt auch andere Situationen, in denen eine leere Strukturliste zurückgegeben werden kann, z. B. wenn die Verbindung zum Smartphone des Nutzers unterbrochen wird oder wenn der Nutzer die Berechtigungen für Ihre App widerrufen hat. Sie sollten diese Fälle in Ihrer App berücksichtigen.

Wenn imperative Programmierung anstelle von reaktiver Programmierung unbedingt erforderlich ist, kann alternativ ein Terminal-Flow-Operator verwendet werden:

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

Bei diesem Aufruf wird auf eine gültige Liste von Gebäuden gewartet, die im Ablauf eingeht. Es kommt zu einem Zeitüberschreitungsfehler, wenn die Liste nicht innerhalb eines von der App festgelegten Zeitlimits empfangen wird.

Struktureigenschaften abrufen

Mit der Liste der Gebäude können Sie auf die Attribute zugreifen:

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

Gebäude anhand des Namens finden

Wenn Sie den Namen einer Struktur kennen, können Sie auch über das Attribut name darauf zugreifen:

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

Dort können Sie auf die Immobilien, Zimmer und Geräte für jede Struktur zugreifen.

Mit mehreren Strukturen arbeiten

Wenn Sie mehrere Strukturen verwenden möchten, müssen Sie für jede Struktur eine separate Referenz abrufen:

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
}

Liste der Räume abrufen

Wenn Sie eine Struktur haben, können Sie eine Liste der Räume abrufen und auf die Attribute für diese Räume zugreifen:

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

Chatroom erstellen

So erstellen Sie einen neuen Raum:

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

Raum löschen

Alternativ können Sie einen Chatroom auch so löschen:

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

Sie können ein Zimmer auch nur mit einer ID löschen:

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

Wenn ein Raum mit Geräten gelöscht wird, befinden sich die Geräte weiterhin im Zuhause, sind aber keinem Raum mehr zugewiesen.

Geräte in einen anderen Raum verschieben

Sobald Sie eine Struktur haben, können Sie Geräte in einen anderen Raum innerhalb dieser Struktur verschieben:

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

Wenn Sie nur Geräte- und Raum-IDs haben, können Sie Geräte auch so verschieben:

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

Name eines Raums ändern

Rufen Sie die Methode setName() auf, um den Namen eines Raums zu ändern:

livingRoom.setName("Living Room")

Namen werden abgeschnitten, wenn sie das Limit von 60 Unicode-Codepunkten (Zeichen) überschreiten. Es werden keine Fehler ausgegeben. Entwickler sind dafür verantwortlich, lange Namen zu verarbeiten. Sie können beispielsweise entscheiden, ob sie Nutzer darüber informieren möchten, dass Namen gekürzt werden.

Automatisierungen

Der Einstiegspunkt für die Automation API ist ein Gebäude. Weitere Informationen zu automatisierten Abläufen in den Home APIs finden Sie unter Automation API on Android overview.

API-Liste

Nachdem eine Instanz von Home erstellt wurde, sind die folgenden Structure APIs darüber zugänglich:

Sobald Sie ein Structure haben, können Sie über dieses auf die folgenden APIs zugreifen:

Einige gängige APIs (z. B. devices(), id und name) sind auch für ein Room verfügbar.