Structure API di Android

Structure API dapat diakses melalui Home API untuk Android. Impor paket ini ke aplikasi Anda:

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

Penanganan error

Metode apa pun di Home API dapat menampilkan HomeException, jadi sebaiknya gunakan blok try-catch untuk menangkap HomeException pada semua panggilan.

Saat menangani HomeException, periksa kolom error.code dan error.message untuk mengetahui penyebab masalah. Mungkin ada juga kode sub-error, jadi panggil metode getSubErrorCodes() dan periksa hasilnya.

Setiap pengecualian yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Panggilan sampel

Mendapatkan daftar struktur

Setelah diinisialisasi, panggilan structures() akan menampilkan Flow struktur yang dapat Anda akses:

// 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 adalah flow yang mungkin tidak langsung menampilkan daftar struktur yang valid. Jika aplikasi Anda reaktif dan berlangganan ke flow tersebut untuk mendorong UI, daftar struktur yang valid pada akhirnya akan ditampilkan. Ada situasi lain saat daftar struktur kosong dapat ditampilkan, misalnya jika ponsel pengguna kehilangan konektivitas atau jika pengguna telah mencabut izin ke aplikasi Anda. Anda harus memastikan untuk menangani kasus ini di aplikasi Anda.

Atau, jika pemrograman imperatif sangat diperlukan, bukan pemrograman reaktif, operator flow terminal dapat digunakan:

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

Panggilan ini menunggu daftar struktur yang valid untuk masuk melalui flow dan waktu tunggu akan habis jika daftar tidak diterima dalam waktu tunggu yang ditetapkan aplikasi.

Mendapatkan properti struktur

Dengan daftar struktur yang ada, Anda dapat mengakses properti untuk struktur tersebut:

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

Menemukan struktur berdasarkan nama

Jika mengetahui nama struktur, Anda juga dapat mengaksesnya menggunakan properti name:

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

Dari sana, properti, ruangan, dan perangkat untuk setiap struktur dapat diakses.

Menangani beberapa struktur

Untuk menggunakan lebih dari satu struktur, dapatkan referensi terpisah ke setiap struktur:

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
}

Mendapatkan daftar ruangan

Dengan struktur yang ada, Anda bisa mendapatkan daftar ruangan dan mengakses properti untuk ruangan tersebut:

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

Membuat ruangan

Untuk membuat ruangan baru:

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

Menghapus ruangan

Atau, Anda dapat menghapus ruangan:

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

Anda juga dapat menghapus ruangan hanya dengan ID:

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

Jika ruangan dengan perangkat dihapus, perangkat akan tetap berada di struktur, tetapi tidak lagi ditetapkan ke ruangan.

Memindahkan perangkat ke ruangan lain

Setelah memiliki struktur, Anda dapat memindahkan perangkat ke ruangan lain dalam struktur tersebut:

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

Jika hanya memiliki ID perangkat dan ruangan, Anda juga dapat memindahkan perangkat:

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

Mengubah nama ruangan

Panggil setName() metode untuk mengubah nama ruangan:

livingRoom.setName("Living Room")

Nama akan dipangkas jika melebihi batas 60 titik kode Unicode (karakter) dan tidak ada error yang akan ditampilkan. Developer bertanggung jawab untuk menangani nama panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipangkas.

Melihat jenis perangkat yang telah diberi izin oleh pengguna

Di ekosistem Google Home, untuk sebagian besar jenis perangkat, pengguna dapat memberikan izin untuk semua perangkat dari jenis tersebut sekaligus. Untuk jenis perangkat yang sensitif atau dibatasi, seperti kunci, kamera, atau bel pintu, pengguna harus memberikan izin satu per satu.

Untuk menentukan apakah pengguna telah memberikan izin untuk mengakses jenis perangkat yang sensitif atau dibatasi, gunakan fungsi consentedDeviceTypes() tingkat Struktur:

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
            }
        }
    }
}

Otomatisasi

Titik entri ke Automation API adalah melalui struktur. Untuk mempelajari Otomatisasi lebih lanjut di Home API, lihat Ringkasan Automation API di Android.