移除裝置

移除裝置時，必須先從結構中停用裝置。使用者可以透過 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。