Usuwanie urządzenia

Usunięcie urządzenia polega na wycofaniu go ze struktury. Użytkownik może to zrobić za pomocą Google Home app (GHA), a aplikacja może programowo wycofać z użytku inteligentne urządzenie domowe. Istnieją ograniczenia dotyczące tego, które urządzenia można usunąć. Usunięcie urządzenia może też wpłynąć na strukturę i sposób korzystania z aplikacji przez użytkowników.

Co możesz usunąć

Za pomocą interfejsów Home API możesz programowo usuwać te urządzenia:

  • Matter urządzeń, do których Twoja aplikacja ma uprawnienia.
  • Matter mostków, pod warunkiem że aplikacja ma dostęp do wszystkich urządzeń połączonych za ich pomocą. Usunięcie mostka spowoduje usunięcie wszystkich urządzeń Matter z nim połączonych.

Czego nie możesz usunąć

Tych urządzeń nie można usunąć automatycznie za pomocą interfejsów Home API:

  • Matter urządzeń, na których Twoja aplikacja nie ma uprawnień użytkownika.
  • Poszczególne urządzenia połączone za pomocą mostka Matter.
  • Cloud-to-cloud połączonych urządzeń.
  • Urządzenia z dwoma ścieżkami (urządzenia, które implementują zarówno Matter, jak i Cloud-to-cloud).

Ważne uwagi przed usunięciem urządzenia

Gdy aplikacja usunie urządzenie, zostanie ono usunięte z całej struktury, co wpłynie na wszystkich użytkowników i wszystkie aplikacje, w tym GHA. W zależności od typu urządzenia wycofanie go z użytku może mieć dodatkowe skutki uboczne:

  • Urządzenia obsługujące wiele typów: jeśli urządzenie ma wiele funkcji, np. inteligentna lampa, która działa też jako hub, usunięcie go spowoduje też usunięcie wszystkich powiązanych urządzeń. Aplikacja powinna informować użytkownika, jeśli zmiana wpłynie na działanie wielu funkcji urządzenia.
  • Historia urządzenia: Usunięcie urządzenia może spowodować usunięcie jego historii.
  • Wspólne miejsca: zachowaj ostrożność podczas usuwania urządzeń ze wspólnych miejsc, ponieważ może to mieć niepożądane konsekwencje dla innych użytkowników.
  • Uwierzytelnianie: usuwanie urządzenia powinno być możliwe tylko na uwierzytelnionych platformach, takich jak telefony komórkowe, a nie na nieuwierzytelnionych urządzeniach, np. telewizorach. Takie działanie stanowi naruszenie Zasad Google Home dla deweloperów.

Usuwanie urządzenia

Sprawdzanie, czy urządzenie kwalifikuje się do usunięcia, jest kosztowne i należy je przeprowadzać tylko w razie potrzeby. Aby sprawdzić, czy urządzenie kwalifikuje się do usunięcia, użyj następującego polecenia:

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.")
}

Urządzenia Matter

Urządzenie Matter można usunąć programowo, jeśli nie znajduje się ono za mostem Matter.

Aby usunąć urządzenie Matter, wywołaj na nim decommissionDevice():

val decommissionedDeviceIds = device.decommissionDevice()

Jeśli wywołanie nie spowoduje błędu, oznacza to, że się powiodło.

Możesz sprawdzić, czy identyfikator urządzenia znajduje się wśród identyfikatorów zwróconych przez decommissionDevice():

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

Urządzenia niematerialne

Urządzeń innych niż Matter nie można usuwać programowo. Aby usunąć urządzenie inne niż Matter, możesz wysłać prośbę o synchronizację (patrz Wysyłanie prośby o synchronizację) lub usunąć integrację Cloud-to-cloud (patrz Usuwanie wdrożonej integracji typu chmura-chmura).

Wywołanie decommissionDevice() na urządzeniu innym niż Matter powoduje zgłoszenie błędu HomeException.

Po usunięciu urządzenia innego niż Matter sprawdź, czy urządzenie jest nadal widoczne, aby potwierdzić, że zostało usunięte:

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

Urządzenia z wieloma źródłami

Urządzenia wielokanałowe to urządzenia, które korzystają z interfejsów Cloud-to-cloud i Matter. Jeśli sprawdzisz, czy takie urządzenie kwalifikuje się do wycofania z użytku, otrzymasz komunikat DecommissionIneligibleReason.multiSourceDevice, który będzie oznaczać, że urządzenie nie może zostać wycofane z użytku, ponieważ pochodzi z wielu źródeł.

Aby usunąć urządzenie z wieloma źródłami, wykonaj te czynności:

  1. Usuń powiązanie Cloud-to-cloud zgodnie z opisem w sekcji Urządzenia inne niż Matter.
  2. Wycofaj urządzenie Matter zgodnie z opisem w sekcji Urządzenia Matter.

Kolejność tych kroków jest ważna. Jeśli spróbujesz wycofać z użytku Matter urządzenie przed usunięciem powiązania Cloud-to-cloud, pojawi się błąd HomeException.