Gerät entfernen

Wenn Sie ein Gerät entfernen, wird es aus der Struktur entfernt. Ein Nutzer kann dies über die Google Home app (GHA) tun und eine App kann ein Smart-Home-Gerät programmatisch außer Betrieb nehmen. Es gibt Einschränkungen hinsichtlich der Geräte, die entfernt werden können. Das Entfernen eines Geräts kann sich auch auf die Struktur und die Nutzerfreundlichkeit Ihrer App auswirken.

Was Sie entfernen können

Sie können die folgenden Geräte programmatisch über die Home APIs entfernen:

  • Matter Geräte, für die Ihre App Berechtigungen hat.
  • Matter-Bridges, sofern Ihre App Zugriff auf alle über die Bridge verbundenen Geräte hat. Wenn du die Bridge entfernst, werden alle damit verbundenen Matter-Geräte entfernt.

Was Sie nicht entfernen können

Die folgenden Geräte können nicht programmatisch über die Home APIs entfernt werden:

  • Matter Geräte, für die Ihrer App Nutzerberechtigungen fehlen.
  • Einzelne Geräte, die über eine Matter-Bridge verbunden sind.
  • Cloud-to-cloud verknüpfte Geräte.
  • Geräte mit zwei Pfaden (Geräte, auf denen sowohl Matter als auch Cloud-to-cloud implementiert sind).

Wichtige Überlegungen vor dem Entfernen eines Geräts

Wenn Ihre App ein Gerät entfernt, wird es aus der gesamten Struktur entfernt. Das wirkt sich auf alle Nutzer und alle Apps aus, einschließlich der GHA. Je nach Gerätetyp kann die Deaktivierung eines Geräts zusätzliche Auswirkungen haben:

  • Geräte mit mehreren Gerätetypen: Wenn ein Gerät mehrere Funktionen hat, z. B. eine smarte Lampe, die auch als Hub fungiert, werden beim Entfernen auch alle zugehörigen Geräte entfernt. Die App sollte den Nutzer informieren, wenn mehrere Gerätefunktionen betroffen sind.
  • Geräteverlauf: Wenn Sie ein Gerät löschen, wird möglicherweise auch der Verlauf des Geräts entfernt.
  • Freigegebene Bereiche: Seien Sie vorsichtig, wenn Sie Geräte in freigegebenen Bereichen löschen, da dies unbeabsichtigte Folgen für andere haben kann.
  • Authentifizierung: Das Entfernen von Geräten sollte nur auf authentifizierten Oberflächen wie einem Smartphone und nicht auf nicht authentifizierten Geräten wie Fernsehern erfolgen. Dies verstößt gegen die Google Home-Richtlinien für Entwickler.

Gerät entfernen

Die Prüfung, ob ein Gerät entfernt werden kann, ist aufwendig und sollte nur bei Bedarf durchgeführt werden. Mit dem folgenden Befehl können Sie prüfen, ob ein Gerät entfernt werden kann:

val eligibility = device.checkDecommissionEligibility()

if (eligibility is DecommissionEligibility.Ineligible) {
  println("The device cannot be decommissioned.")
} else if (eligibility is DecommissionEligibility.EligibleWithSideEffects) {
  println("The device can be decommissioned but there will be side effects on other devices.")
} else if (eligibility is DecommissionEligibility.Eligible) {
  println("The device can be decommissioned.")
}

Matter-Geräte

Sie können ein Matter-Gerät programmatisch entfernen, wenn es sich nicht hinter einer Matter-Bridge befindet.

Wenn Sie ein Matter-Gerät entfernen möchten, rufen Sie decommissionDevice() auf:

val decommissionedDeviceIds = device.decommissionDevice()

Wenn beim Aufruf kein Fehler ausgegeben wird, war er erfolgreich.

Sie können prüfen, ob die ID des Geräts zu den von decommissionDevice() zurückgegebenen IDs gehört: 

if (decommissionedDeviceIds.contains(deviceId)) {
  println("Decommission successful!")
} else {
  println("Decommission failed!")
}

Nicht Matter-kompatible Geräte

Geräte, die nicht Matter-kompatibel sind, können nicht programmatisch entfernt werden. Wenn Sie ein Gerät entfernen möchten, das nicht Matter-kompatibel ist, können Sie eine Synchronisierungsanfrage senden (siehe Synchronisierung anfordern) oder die Cloud-to-cloud-Integration löschen (siehe Gestartete Cloud-zu-Cloud-Integration löschen).

Wenn Sie decommissionDevice() auf einem Gerät aufrufen, das nicht Matter ist, wird eine HomeException ausgelöst.

Nachdem Sie ein Gerät entfernt haben, das nicht Matter ist, prüfen Sie, ob es noch vorhanden ist, um zu bestätigen, dass es erfolgreich entfernt wurde:

var removedDevice: HomeDevice? = null
runBlockingCustom {
  try {
    removedDevice = homeManager.devices().get(deviceId)
  } catch (exception: Exception) {
    println("removal successful!")
  }
}
if (removedDevice != null) {
  println("removal failed!")
}

Geräte mit mehreren Quellen

Geräte mit mehreren Quellen sind Geräte, die sowohl die Cloud-to-cloud- als auch die Matter-APIs verwenden. Wenn Sie die Voraussetzungen für die Außerbetriebnahme eines solchen Geräts prüfen, erhalten Sie die Meldung DecommissionIneligibleReason.multiSourceDevice. Das bedeutet, dass das Gerät nicht außer Betrieb genommen werden kann, da es mehrere Quellen hat.

So entfernen Sie ein Gerät mit mehreren Quellen:

  1. Entferne die Cloud-to-cloud-Verknüpfung, wie unter Nicht Matter-kompatible Geräte beschrieben.
  2. Nimm das Matter-Gerät wie unter Matter-Geräte beschrieben außer Betrieb.

Die Reihenfolge dieser Schritte ist wichtig. Wenn Sie versuchen, das Matter-Gerät außer Betrieb zu nehmen, bevor Sie die Cloud-to-cloud-Verknüpfung entfernen, wird eine HomeException ausgelöst.