The Key Value API provides new custom data management APIs for Device, Room, and Automation objects. The lifecycle of the custom data is strictly scoped to the lifecycle of the object it is associated with. For example, custom data (like "Lucy's room") associated with a Room object will be automatically deleted, moved, or transferred (across structures) with the Room object.
The Kotlin API change is centered on the
hasCustomAppData
interface and provides extensions to the objects that the custom application
data belongs to, and include the standard create, read, update, and delete
(CRUD) functions.
Device example
val device = homeClient.devicesWithLogging().findDeviceByName(deviceName)
var response = device.getValue(key)
println("Before: $response")
device.updateValue(key, value)
response = device.getValue(key)
println("After: $response")
device.deleteValue(key)
Room example
val room = homeClient.rooms().findRoomByName(roomName)
room.updateValue("nickname", "Lucy's Room")
val response = room.getValue("nickname")
room.deleteValue("nickname")
Automation example
val automation = homeClient.automations().findAutomationByName(automationName)
var response = automation.getValue(key)
println("Before: $response")
automation.updateValue(key, value)
response = automation.getValue(key)
println("After: $response")
automation.deleteValue(key)
Restrictions
- The key must be a string of valid UTF-8 characters, with a maximum length of 128. The key can be an empty string.
- The value must be a string of valid UTF-8 characters, with a maximum length of 1024. The value can be an empty string.
- Each object can have 10 rows of key value pairs.