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, dlatego 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 wywołania

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 zwracać od razu prawidłowej listy 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

Mając 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.

Wyświetlanie typów urządzeń, do których użytkownik przyznał uprawnienia

W ekosystemie Google Home użytkownicy mogą przyznawać uprawnienia do wszystkich urządzeń danego typu jednocześnie. W przypadku urządzeń wrażliwych lub objętych ograniczeniami, takich jak zamki, kamery czy dzwonki do drzwi, użytkownicy muszą przyznawać uprawnienia indywidualnie.

Aby sprawdzić, czy użytkownik przyznał uprawnienia dostępu do typu urządzenia, który jest wrażliwy lub ma ograniczenia, użyj funkcji na poziomie struktury:consentedDeviceTypes()

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

Automatyzacja

Punkt wejścia do interfejsu Automation API jest dostępny za pomocą struktury. Więcej informacji o automatyzacjach w interfejsach Home API znajdziesz w artykule Omówienie interfejsu Automation API na Androidzie.