Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

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 error.code dan error.message untuk mengetahui penyebab masalahnya. Mungkin juga ada sub-kode 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.

Contoh panggilan

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

API structures() adalah alur 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 alur terminal dapat digunakan:

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

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

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

Buat ruang

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

Mengubah nama ruangan

Panggil metode setName() untuk mengubah nama ruangan:

livingRoom.setName("Living Room")

Nama akan dipotong 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.

Dalam ekosistem Google Home, untuk sebagian besar jenis perangkat, pengguna dapat memberikan izin untuk semua perangkat dengan jenis tersebut sekaligus. Untuk jenis perangkat sensitif atau terbatas, seperti smart lock, kamera, atau bel pintu, pengguna harus memberikan izin kepada perangkat tersebut satu per satu.

Untuk menentukan apakah pengguna telah memberikan izin untuk mengakses jenis perangkat sensitif atau terbatas, gunakan fungsi consentedDeviceTypes() level 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
            }
        }
    }
}

Grup perangkat

Grup perangkat mewakili kumpulan perangkat yang ditentukan pengguna dalam satu struktur.

Seperti ruang fisik, grup perangkat termasuk dalam satu struktur. Namun, tidak seperti ruangan, grup perangkat adalah pengelompokan logis. Perangkat dapat termasuk dalam beberapa grup perangkat secara bersamaan. Grup perangkat dapat berisi hingga 100 perangkat.

Grup perangkat direpresentasikan oleh entitas Group, yang berbeda dari HomeDevice.

Membuat grup perangkat

Gunakan GroupManagement pada struktur untuk membuat grup perangkat:

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

Mengelola keanggotaan grup

Untuk menambahkan anggota ke grup yang ada:

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

Untuk menghapus anggota dari grup:

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

Mengubah nama grup perangkat

Untuk mengganti nama grup perangkat, perbarui atribut nama di GroupTrait grup:

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

Menghapus grup perangkat

Untuk menghapus grup perangkat dari struktur:

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

Otomatisasi

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