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

Fehlerbehebung

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 bei der Behandlung 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.

Alle nicht behandelten Ausnahmen führen zum Absturz Ihrer App.

Weitere Informationen finden Sie unter Fehlerbehebung.

Beispielaufrufe

Liste der Strukturen 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 Flow, der möglicherweise nicht sofort eine gültige Liste von Strukturen 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 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 Strukturen durch den Flow kommt, und es kommt zu einer Zeitüberschreitung, wenn die Liste nicht innerhalb eines von der App festgelegten Zeitlimits empfangen wird.

Struktureigenschaften abrufen

Mit der Liste der Strukturen können Sie auf die Eigenschaften 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}")

Struktur anhand des Namens finden

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

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

Von dort aus sind Eigenschaften, Räume und Geräte für jede Struktur zugänglich.

Mit mehreren Strukturen arbeiten

Wenn Sie mehr als eine Struktur verwenden möchten, rufen Sie für jede Struktur 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 einer Struktur können Sie eine Liste der Räume abrufen und auf die Eigenschaften 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 in der Struktur, 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")))

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 ausgegeben. Entwickler sind für die Verarbeitung langer Namen verantwortlich und können beispielsweise entscheiden, ob sie Nutzer darüber informieren möchten, dass Namen abgeschnitten werden.

Gerätetypen aufrufen, für die ein Nutzer Berechtigungen erteilt hat

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 Strukturebene, 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 eine Struktur. Weitere Informationen zu Automatisierungen in den Home APIs finden Sie unter Automation API auf Android – Übersicht.