Struktura interfejsu API

Do interfejsów API struktury można uzyskać dostęp za pomocą interfejsów API Home. Zaimportuj do aplikacji te pakiety:

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 API Home może wywołać błądHomeException, dlatego zalecamy użycie bloku try-catch, aby przechwytywać błądHomeException we wszystkich wywołaniach.

Podczas obsługi HomeException sprawdź pola code i message, aby dowiedzieć się, co poszło nie tak.

Każdy nieobsługiwany wyjątek spowoduje awarię aplikacji.

Więcej informacji znajdziesz w artykule Postępowanie z błędami.

Przykładowe rozmowy

Pobieranie listy struktur

Po zainicjowaniu wywołanie structures() zwraca dostępne dla Ciebie struktury przepływu:

// 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 API structures() to przepływ, który może nie zwracać od razu prawidłowej listy struktur. Jeśli Twoja aplikacja jest reaktywna i subskrybuje ten przepływ danych, aby sterować interfejsem użytkownika, powinna zwracać prawidłową listę struktur. Pusta lista struktury może zostać zwrócona również w innych sytuacjach, np. gdy telefon użytkownika straci łączność lub użytkownik cofnie uprawnienia do aplikacji. W takich przypadkach aplikacja powinna odpowiednio zareagować.

Jeśli zamiast programowania imperatywnego konieczne jest programowanie imperatywne, możesz użyć operatora terminal flow:

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

Ten wywołanie czeka na prawidłową listę struktur, która ma być przesłana w ramach przepływu, i wygasa, jeśli lista nie zostanie odebrana w określonym czasie.

Pobieranie właściwości struktury

Po uzyskaniu listy 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}")

Znajdowanie struktury według nazwy

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

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

Tutaj możesz przeglądać właściwości, pomieszczenia i urządzenia w poszczególnych strukturach.

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

Po wybraniu struktury możesz uzyskać listę pokoi i uzyskać do nich dostęp:

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 identyfikator:

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

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

Przenoszenie urządzeń do innego pomieszczenia

Po utworzeniu struktury możesz przenieść urządzenia do innego pokoju w ramach tej struktury:

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ądzenia i pokoju, możesz też przenieść urządzenia:

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

Automatyzacja

Punkt wejścia do interfejsu Automation API to struktura. Więcej informacji o automatyzacjach w interfejsach API Home znajdziesz w artykule Projektowanie automatyzacji.

Lista interfejsów API

Po utworzeniu instancji Home są dostępne te interfejsy Structure API:

Gdy masz konto Structure, możesz korzystać z tych interfejsów API:

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