APIs strukturieren

Auf Gebäude-APIs kann über die Home APIs zugegriffen werden. Importieren Sie die folgenden Pakete in Ihre App:

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

Fehlerbehandlung

Bei jeder Methode in den Home APIs kann eine HomeException geworfen werden. Wir empfehlen daher, einen try-catch-Block zu verwenden, um HomeException bei allen Aufrufen zu fangen.

Prüfen Sie bei der Verarbeitung von HomeException die Felder code und message, um herauszufinden, was schiefgelaufen ist.

Alle nicht behandelten 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 Fluss von Strukturen zurück, auf die du zugreifen kannst:

// 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 Ablauf abonniert, um die Benutzeroberfläche zu steuern, sollte schließlich eine gültige Liste der Gebäude zurückgegeben werden. Es gibt auch andere Situationen, in denen eine leere Strukturliste zurückgegeben werden kann, z. B. wenn die Verbindung des Smartphones des Nutzers unterbrochen wird oder der Nutzer die Berechtigungen für Ihre App widerrufen hat. Sie sollten diese Fälle in Ihrer App berücksichtigen.

Alternativ kann ein Terminalablaufoperator verwendet werden, wenn anstelle der reaktiven Programmierung eine imperative Programmierung erforderlich ist:

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

Bei diesem Aufruf wird gewartet, bis eine gültige Liste von Gebäuden über den Ablauf gesendet wird. Wenn die Liste nicht innerhalb des von der App festgelegten Zeitlimits empfangen wird, tritt ein Zeitüberschreitungsfehler auf.

Gebäudeeigenschaften abrufen

Mit der Liste der Gebäude können Sie auf die zugehörigen Properties 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 nach Name suchen

Wenn du den Namen eines Gebäudes kennst, kannst du auch über das Attribut name darauf zugreifen:

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

Von dort aus können Sie auf Unterkünfte, Zimmer und Geräte für jedes Gebäude zugreifen.

Mit mehreren Strukturen arbeiten

Wenn Sie mehrere Strukturen verwenden möchten, müssen Sie für jede Struktur einen separaten Verweis 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 ein Gebäude ausgewählt haben, können Sie eine Liste der zugehörigen Räume abrufen und auf die zugehörigen Unterkünfte 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 Raum auch so löschen:

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

Sie können einen Raum 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 Gebäude, sind aber keinem Raum mehr zugewiesen.

Geräte in einen anderen Raum verschieben

Sobald Sie ein Gebäude haben, können Sie Geräte in einen anderen Raum innerhalb dieses Gebäudes 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")))

Automatisierungen

Der Einstiegspunkt in die Automation API ist eine Struktur. Weitere Informationen zu Automatisierungen in den Home APIs finden Sie unter Automatisierung entwerfen.

API-Liste

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

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

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