API Struktur

Structure API dapat diakses melalui Home API. Impor paket ini ke 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 menampilkan HomeException, jadi sebaiknya gunakan blok try-catch untuk menangkap HomeException di semua panggilan.

Saat menangani HomeException, periksa kolom code dan message untuk mengetahui masalahnya.

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 Alur 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 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 alur terminal dapat digunakan:

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

Panggilan ini menunggu daftar struktur yang valid untuk masuk melalui alur dan waktu tunggu habis 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.

Menggunakan 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 yang ada, Anda bisa mendapatkan daftar ruangan dan mengakses propertinya:

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

Otomatisasi

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

Daftar API

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

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

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