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 Swift API change is centered on the
CustomAppData
controller 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
guard let device = home.devices.first(where: { $0.name == deviceName }) else { return }
var response = try await device.customAppData[key]
print("Before: \(response)")
try await device.customAppData.update(key: key, value: value)
response = try await device.customAppData[key]
print("After: \(response)")
try await device.customAppData.delete(key)
Room example
guard let room = home.rooms.first(where: { $0.name == roomName }) else { return }
try await room.customAppData.update(key: "nickname", value: "Lucy's Room")
let response = try await room.customAppData["nickname"]
try await room.customAppData.delete("nickname")
Automation example
guard let automation = home.automations.first(where: { $0.name == automationName }) else { return }
var response = try await automation.customAppData[key]
print("Before: \(response)")
try await automation.customAppData.update(key: key, value: value)
response = try await automation.customAppData[key]
print("After: \(response)")
try await automation.customAppData.delete(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.