移除设备

移除设备是指从结构中停用设备。用户可以使用 Google Home app (GHA) 执行此操作，应用也可以通过编程方式停用智能家居设备。可以移除的设备存在限制。此外，移除设备可能会影响应用的结构和用户体验。

您可以移除的内容

您可以通过 Home API 以编程方式移除以下设备：

  • 您的应用拥有权限的 Matter 部设备。
  • Matter 网桥，前提是您的应用有权访问通过该网桥连接的所有设备。移除网桥会移除与其连接的所有 Matter 设备。

无法移除的内容

以下设备无法通过 Home API 以编程方式移除：

  • 您的应用缺少用户权限的 Matter 个设备。
  • 通过 Matter 网桥连接的各个设备。
  • 已关联 Cloud-to-cloud 部设备。
  • 双路径设备（同时实现 Matter 和 Cloud-to-cloud 的设备）。

移除设备前的重要注意事项

当您的应用移除设备时，该设备会从整个结构中移除，从而影响所有用户和所有应用，包括 GHA。根据设备类型，停用设备可能会产生其他副作用：

  • 实现多种设备类型的设备：如果设备具有多种功能（例如，既是智能灯又是中枢），移除该设备也会移除所有关联的设备。如果多个设备功能会受到影响，应用应告知用户。
  • 设备历史记录：删除设备可能会导致设备的历史记录被移除。
  • 共享界面：删除共享界面上的设备时请务必谨慎，因为这可能会对他人造成意想不到的后果。
  • 身份验证：设备移除操作应仅在经过身份验证的界面（例如手机）上执行，而不应在未经身份验证的设备（例如电视）上执行。 这样做会违反 Google Home 开发者政策。

移除设备

检查设备是否符合移除条件成本高昂，因此只有在必要时才应进行检查。如需检查设备是否符合移除条件，请使用以下命令：

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 设备

如果 Matter 设备不在 Matter 网桥后面，您可以通过编程方式移除该设备。

如需移除 Matter 设备，请对其调用 decommissionDevice()：

val decommissionedDeviceIds = device.decommissionDevice()

如果调用未抛出错误，则表示成功。

您可以检查设备的 ID 是否包含在 decommissionDevice() 返回的 ID 中：

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

非 Matter 设备

无法以编程方式移除非 Matter 设备。如需移除非 Matter 设备，您可以发出同步请求（请参阅请求同步），也可以删除 Cloud-to-cloud 集成（请参阅删除已启动的云到云集成）。

如果您在非 Matter 设备上调用 decommissionDevice()，系统会抛出 HomeException。

移除非 Matter 设备后，请检查设备是否存在，以验证是否已成功移除：

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

多源设备

多来源设备是指同时使用 Cloud-to-cloud 和 Matter API 的设备。如果您检查此类设备的停用资格，会收到 DecommissionIneligibleReason.multiSourceDevice，表明由于设备是多来源的，因此无法停用。

如需移除多来源设备，请按以下步骤操作：

  1. 按照非 Matter 设备中所述移除 Cloud-to-cloud 关联。
  2. 按照 Matter 设备中所述停用 Matter 设备。

这些步骤的顺序很重要。如果您尝试在移除 Cloud-to-cloud 关联之前停用 Matter 设备，系统会抛出 HomeException。