Usuwanie urządzenia

Usunięcie urządzenia wiąże się z jego wycofaniem ze struktury. Użytkownik może to zrobić za pomocą Google Home app (GHA), a aplikacja może programowo wycofać inteligentne urządzenie domowe z użytku. 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ń, na 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ń, w przypadku 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ądzeń: 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. Jest to naruszenie zasad dla deweloperów Google Home.

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 można usunąć, użyj tego 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żesz usunąć programowo, jeśli nie jest ono połączone z mostkiem Matter.

Aby usunąć Matter urządzenie, zadzwoń decommissionDevice() na nie:

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 inne niż Matter

Urządzeń innych niż Matter nie można usuwać programowo. Aby usunąć urządzenie inne niż Matter, możesz wysłać żądanie synchronizacji (patrz Wysyłanie żądania synchronizacji) lub usunąć integrację Cloud-to-cloud (patrz Usuwanie uruchomionej integracji typu chmura-chmura).

Jeśli wywołasz funkcję decommissionDevice() na urządzeniu, które nie jest urządzeniem Matter, zostanie zgłoszony wyjątek HomeException.

Po usunięciu urządzenia innego niż Matter sprawdź, czy urządzenie 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 wielozródłowe to urządzenia, które korzystają z interfejsów API 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ć urządzenie Matter przed usunięciem powiązania Cloud-to-cloud, zostanie zgłoszony błąd HomeException.