Structure API di Android

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

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

Penanganan error

Setiap metode di Home API dapat memunculkan HomeException, jadi sebaiknya gunakan blok try-catch untuk menangkap HomeException pada semua panggilan.

Saat menangani HomeException, periksa kolom code dan message untuk mengetahui apa yang salah.

Setiap pengecualian yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Contoh panggilan

Mendapatkan daftar struktur

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

// 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 alur yang mungkin tidak langsung menampilkan daftar struktur yang valid. Jika aplikasi Anda reaktif dan berlangganan alur tersebut untuk mendorong UI, daftar struktur yang valid pada akhirnya akan ditampilkan. Ada situasi lain saat daftar struktur kosong dapat ditampilkan, misalnya jika konektivitas ponsel pengguna terputus 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 alur terminal dapat digunakan:

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

Panggilan ini menunggu daftar struktur yang valid masuk melalui alur dan berakhir jika daftar tidak diterima dalam waktu tunggu yang ditetapkan aplikasi.

Mendapatkan properti struktur

Dengan daftar struktur yang ada, Anda dapat mengakses propertinya:

// 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.

Bekerja dengan beberapa struktur

Untuk menggunakan lebih dari satu struktur, dapatkan referensi terpisah untuk 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 ruang

Dengan struktur di tangan, Anda bisa mendapatkan daftar ruang dan mengakses properti untuk ruang 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}")

Buat ruang

Untuk membuat ruangan baru:

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

Menghapus ruangan

Atau, Anda dapat menghapus ruang:

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

Anda juga dapat menghapus kamar hanya dengan ID:

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

Jika ruangan dengan perangkat dihapus, perangkat akan tetap berada dalam 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 metode setName() untuk mengubah nama ruangan:

livingRoom.setName("Living Room")

Nama akan dipangkas jika melebihi batas 60 poin 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.

Otomatisasi

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

Daftar API

Setelah instance Home dibuat, API Struktur berikut dapat diakses melalui instance tersebut:

Setelah Anda memiliki Structure, API berikut dapat diakses melalui Structure tersebut:

Beberapa API umum (seperti devices(), id, dan name) juga tersedia untuk Room.