Interfejsy Structure API na Androidzie

Dostęp do interfejsów Structure API można uzyskać za pomocą interfejsów Home API na Androida. 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 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()

structures() API 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, aby sterować interfejsem, powinna ostatecznie zwrócić prawidłową listę struktur. Istnieją inne sytuacje, w których może zostać zwrócona pusta lista struktur, np. gdy telefon użytkownika utraci łączność lub gdy użytkownik cofnie uprawnienia do Twojej 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 końcowego:

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

To wywołanie czeka na prawidłową listę struktur, która ma się pojawić w przepływie, 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ę domów, 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ć nowy pokój:

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

Zmiana 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 zostaną skrócone.

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 urządzenia typu wrażliwego lub o ograniczonym dostępie, 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
            }
        }
    }
}

Grupy urządzeń

Grupa urządzeń to zdefiniowany przez użytkownika zbiór urządzeń w ramach jednej struktury.

Podobnie jak pomieszczenia fizyczne, grupy urządzeń należą do jednej struktury. W przeciwieństwie do pomieszczeń grupy urządzeń są jednak grupami logicznymi. Urządzenie może należeć do kilku grup urządzeń jednocześnie. Grupy urządzeń mogą zawierać maksymalnie 100 urządzeń.

Grupy urządzeń są reprezentowane przez element Group, który różni się od elementu HomeDevice.

Tworzenie grupy urządzeń

Aby utworzyć grupę urządzeń, użyj struktury GroupManagement:

val groupManagement = structure.trait(GroupManagementTrait)
val response = groupManagement?.createUserDefinedGroup(
  name = "Living room lights",
  memberDeviceObjectIds = listOf(light1.id.id, light2.id.id)
)

Zarządzanie członkostwem w grupach

Aby dodać członków do istniejącej grupy:

structure.trait(GroupManagementTrait)?.addGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light3.id.id)
)

Aby usunąć użytkowników z grupy:

structure.trait(GroupManagementTrait)?.removeGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light1.id.id)
)

Zmiana nazwy grupy urządzeń

Aby zmienić nazwę grupy urządzeń, zaktualizuj atrybut nazwy w GroupTrait grupy:

group.trait(GroupTrait)?.update {
  name = "Movie corner"
}

Usuwanie grupy urządzeń

Aby usunąć grupę urządzeń ze struktury:

structure.trait(GroupManagementTrait)?.deleteGroup(
  groupObjectId = group.id.id
)

Automatyzacja

Punktem wejścia do interfejsu Automation API jest dom. Więcej informacji o automatyzacjach w interfejsach Home API znajdziesz w artykule Omówienie interfejsu Automation API na Androidzie.