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 besitzt.
  • 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 Nebenwirkungen 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 erfolgen. 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.

Um ein Matter-Gerät zu entfernen, rufen Sie decommissionDevice() darauf auf:

val decommissionedDeviceIds = device.decommissionDevice()

Wenn der Aufruf keinen Fehler auslöst, war er erfolgreich.

Sie können überprüfen, ob die Geräte-ID zu denjenigen gehört, die von decommissionDevice() zurückgegeben werden:

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

Nicht Matter-kompatible Geräte

Geräte, die nicht Matter 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-Ausnahme 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!")
}

Multiquellengeräte

Geräte mit mehreren Quellen sind Geräte, die sowohl die Cloud-to-cloud- als auch die Matter-APIs verwenden. Wenn Sie die Stilllegungsberechtigung eines solchen Geräts überprüfen, erhalten Sie DecommissionIneligibleReason.multiSourceDevice, was bedeutet, dass das Gerät aufgrund seiner Mehrquellenfähigkeit nicht stillgelegt werden kann.

Um ein Gerät mit mehreren Quellen zu entfernen, gehen Sie wie folgt vor:

  1. Entfernen Sie die Cloud-to-cloud-Assoziation wie in Nicht-Materie-Bauelemente 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-Zuordnung entfernen, wird ein HomeException-Fehler ausgelöst.