Interfejsy Structure API na Androidzie

Dostęp do interfejsów Structure API można uzyskać za pomocą interfejsów Home API na Androida. Zaimportuj te pakiety do aplikacji:

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

Obsługa błędów

Każda metoda w interfejsach Home API może zgłosić wyjątek HomeException, dlatego zalecamy używanie bloku try-catch do przechwytywania wyjątku HomeException we wszystkich wywołaniach.

Podczas obsługi HomeException sprawdź pola error.code i  error.message, aby dowiedzieć się, co poszło nie tak. Mogą też występować kody błędów podrzędnych, więc wywołaj metodę getSubErrorCodes() i sprawdź wynik.

Wszelkie nieobsłużone wyjątki spowodują awarię aplikacji.

Więcej informacji znajdziesz w sekcji Obsługa błędów.

Przykładowe połączenia

Pobieranie listy struktur

Po zainicjowaniu wywołanie structures() zwraca dostępny dla Ciebie przepływ struktur:

// Get a flow of all structures accessible to the user
val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allStructures: Set<Structure> = allStructuresFlow.list()

Interfejs structures() API to proces, który może nie od razu zwracać prawidłową listę struktur. Jeśli Twoja aplikacja jest reaktywna i subskrybuje ten przepływ, aby sterować interfejsem, powinna ostatecznie zwrócić prawidłową listę struktur. Pusta lista struktur może być zwracana w innych sytuacjach, np. gdy telefon użytkownika utraci łączność lub gdy użytkownik cofnie uprawnienia aplikacji. Pamiętaj, aby obsługiwać te przypadki w swojej aplikacji.

Jeśli zamiast programowania reaktywnego konieczne jest programowanie imperatywne, można użyć operatora przepływu terminala:

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

To wywołanie czeka na prawidłową listę struktur, która ma zostać przekazana w ramach przepływu, i przekracza limit czasu, jeśli lista nie zostanie odebrana w określonym przez aplikację czasie.

Pobieranie właściwości struktury

Gdy masz już listę struktur, możesz uzyskać dostęp do ich właściwości:

// Get a flow on a structure. Flow emits new values on structure metadata changes: name.
val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

// Get structure properties
println("id ${structure.id}")
println("name ${structure.name}")

Znajdź strukturę według nazwy

Jeśli znasz nazwę struktury, możesz też uzyskać do niej dostęp za pomocą właściwości name:

val myHome = home.structures().list().first { it.name == "My home" }

Stamtąd można uzyskać dostęp do usług, pomieszczeń i urządzeń w każdym domu.

Praca z wieloma strukturami

Aby użyć więcej niż jednej struktury, uzyskaj osobne odwołanie do każdej z nich:

var structure1: Structure? = null
var structure2: Structure? = null

try {
  structure1 = home.structures().list().firstOrNull { it.name == "Main House" }
} catch (e: HomeException) {
  // Code for handling the exception
}
try {
  structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" }
} catch (e: HomeException) {
  // Code for handling the exception
}

Pobieranie listy pokoi

Mając strukturę, możesz uzyskać listę pokoi i dostęp do ich właściwości:

val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms()
val allRooms: Set<Room> = allRoomsFlow.list()
val room: Room = allRooms.first()

println("id ${room.id}")
println("name ${room.name}")

Utwórz pokój

Aby utworzyć nowe pomieszczenie:

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

Usuwanie pomieszczenia

Możesz też usunąć pokój:

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

Możesz też usunąć pokój, podając tylko jego identyfikator:

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

Jeśli usuniesz pomieszczenie z urządzeniami, urządzenia nadal będą w strukturze, ale nie będą już przypisane do pomieszczenia.

Przenoszenie urządzeń do innego pomieszczenia

Gdy masz już strukturę, możesz przenieść urządzenia do innego pomieszczenia w jej obrębie:

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

Jeśli masz tylko identyfikatory urządzeń i pomieszczeń, możesz też przenieść urządzenia:

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

Zmienianie nazwy pomieszczenia

Wywołaj metodę setName(), aby zmienić nazwę pokoju:

livingRoom.setName("Living Room")

Nazwy zostaną obcięte, jeśli przekroczą limit 60 punktów kodowych Unicode (znaków), i nie zostaną zgłoszone żadne błędy. Deweloperzy odpowiadają za obsługę długich nazw i mogą na przykład zdecydować, czy chcą informować użytkowników o tym, że nazwy będą skracane.

Automatyzacja

Punktem wejścia do interfejsu Automation API jest struktura. Więcej informacji o automatyzacjach w interfejsach Home API znajdziesz w tym artykule.

Lista interfejsów API

Po utworzeniu instancji Home można uzyskać dostęp do tych interfejsów API struktury:

Gdy uzyskasz Structure, możesz za jego pomocą uzyskać dostęp do tych interfejsów API:

Niektóre popularne interfejsy API (np. devices(), id i name) są też dostępne w przypadku Room.