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

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

structures() API 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 flow 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 habis jika daftar tidak diterima dalam waktu tunggu yang ditentukan 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 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 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 yang memiliki 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 Anda 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 ruang:

livingRoom.setName("Living Room")

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

Melihat jenis perangkat yang izinnya telah diberikan oleh pengguna

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

Untuk menentukan apakah pengguna telah memberikan izin untuk mengakses jenis perangkat yang sensitif atau dibatasi, 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. Keanggotaan grup dipertahankan di layanan Google dan dapat dilihat oleh anggota lain dari struktur dan aplikasi lain yang memiliki akses ke struktur.

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

Anda dapat berinteraksi dengan perangkat dalam grup dengan melakukan iterasi pada perangkat anggotanya secara langsung (lihat Berinteraksi dengan perangkat anggota grup) atau dengan menargetkan bagian jenis perangkat di DeviceGroup (lihat Mengontrol grup perangkat).

Mendapatkan daftar grup perangkat

Untuk mengamati semua grup perangkat dalam struktur, panggil home.entities(DeviceGroup) dan filter menurut ID struktur:

home.entities(DeviceGroup).collect { allGroups ->
  val structureGroups = allGroups.filter { it.structureId == structure.id }
  for (group in structureGroups) {
    val groupName = group.trait(Group)?.Name
    println("Found group: $groupName with ID: ${group.id.id}")
  }
}

Berinteraksi dengan perangkat anggota grup

Melakukan iterasi pada perangkat anggota grup dengan group.devices() memberi Anda kontrol yang mendetail atas setiap anggota, memungkinkan Anda mengelompokkan perintah dalam satu permintaan, dan memungkinkan Anda menggabungkan atau menulis atribut di seluruh anggota.

Misalnya, untuk mengirim satu permintaan batch dengan perintah untuk karakteristik di semua anggota grup yang kompatibel:

val members = group.devices(enableMultipartDevices = true).first()
val onOffTraits = members.mapNotNull { device ->
  device.partOrNull(OnOffLightDevice).first()?.standardTraits?.onOff
}

val responses = home.sendBatchedCommands {
  onOffTraits.map { onOff ->
    add(onOff.onBatchable())
  }
}

for (response in responses) {
  response.getOrThrow()
}

Anda juga dapat memperbarui atribut di semua perangkat anggota yang cocok dalam grup (misalnya, menetapkan onTransitionTime ke 1u di semua anggota DimmableLightDevice) dan menunggu penyelesaian dalam batas waktu:

val members = group.devices(enableMultipartDevices = true).first()

withTimeout(5.seconds) {
  members.map { device ->
    async {
      val light = device.partOrNull(DimmableLightDevice).first()
      val levelControl = light?.standardTraits?.levelControl
      if (
        levelControl?.supports(
          LevelControl.Attribute.onTransitionTime
        ) == true
      ) {
        levelControl.update { setOnTransitionTime(1u) }
      }
    }
  }.awaitAll()
}

Untuk menggabungkan atribut di seluruh anggota grup, seperti menemukan colorTempPhysicalMaxMireds minimum di semua lampu suhu warna dalam grup:

val members = group.devices(enableMultipartDevices = true).first()
val minMaxMireds: UShort? = members.mapNotNull { device ->
  val light = device.partOrNull(ColorTemperatureLightDevice).first()
  light?.standardTraits?.colorControl?.colorTempPhysicalMaxMireds
}.minOrNull()

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