Gebäude-APIs unter Android

Auf die Gebäude-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 Behandeln von HomeException, die Felder error.code und error.message, um herauszufinden, was schiefgelaufen ist. Es kann auch Unterfehlercodes geben. Rufen Sie daher die getSubErrorCodes() Methode auf und prüfen Sie das Ergebnis.

Nicht behandelte Ausnahmen führen zum Absturz Ihrer App.

Weitere Informationen finden Sie unter Fehlerbehandlung.

Beispielaufrufe

Liste der Gebäude abrufen

Nach der Initialisierung gibt ein structures()-Aufruf einen Flow von Gebäuden 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 Flow, 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 Gebäuden zurückgegeben werden. Es gibt auch andere Situationen, in denen eine leere Gebäudeliste 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 behandeln.

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

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

Dieser Aufruf wartet darauf, dass eine gültige Liste von Gebäuden durch den Flow kommt, und es kommt zu einer Zeitüberschreitung, wenn die Liste nicht innerhalb eines von der App festgelegten Zeitlimits empfangen wird.

Gebäudeattribute 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 eines Gebäudes kennen, können Sie auch über das Attribut name darauf zugreifen:

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

Von dort aus sind Attribute, Räume und Geräte für jedes Gebäude zugänglich.

Mit mehreren Gebäuden arbeiten

Wenn Sie mehr als ein Gebäude verwenden möchten, rufen Sie für jedes Gebäude eine separate Referenz ab:

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

Mit einem Gebäude können Sie eine Liste der Räume abrufen und auf die Attribute 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}")

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

Namen eines Raums ändern

Rufen Sie die setName() Methode 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 ausgelöst. Entwickler sind für die Behandlung langer Namen verantwortlich und können beispielsweise entscheiden, ob sie Nutzer darüber informieren möchten, dass Namen abgeschnitten werden.

Im Google Home-Ökosystem können Nutzer für die meisten Gerätetypen Berechtigungen für alle Geräte dieses Typs gleichzeitig erteilen. Bei sicherheits- oder datenschutzrelevanten oder eingeschränkten Gerätetypen wie Schlössern, Kameras oder Türklingeln müssen Nutzer die Berechtigung einzeln erteilen.

Verwenden Sie die Funktion consentedDeviceTypes() auf Gebäudeebene, um zu ermitteln, ob ein Nutzer die Berechtigung für den Zugriff auf einen sicherheits- oder datenschutzrelevanten oder eingeschränkten Gerätetyp erteilt hat:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

Automatisierungen

Der Einstiegspunkt für die Automation API ist ein Gebäude. Weitere Informationen zu Automatisierungen in den Home APIs finden Sie unter Übersicht über die Automation API auf Android.