鍵值 API

Key Value API 提供新的自訂資料管理 API，適用於裝置、房間和自動化物件。自訂資料的生命週期嚴格來說，是與其相關聯物件的生命週期範圍。舉例來說，與 Room 物件相關聯的自訂資料 (例如「Lucy's room」) 會隨著 Room 物件自動刪除、移動或轉移 (跨結構)。

Kotlin API 變更以 hasCustomAppData 介面為中心，並提供自訂應用程式資料所屬物件的擴充功能，以及標準的建立、讀取、更新和刪除 (CRUD) 函式。

裝置範例

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)

房間範例

val room = homeClient.rooms().findRoomByName(roomName)
room.updateValue("nickname", "Lucy's Room")
val response = room.getValue("nickname")
room.deleteValue("nickname")

自動化動作範例

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)

限制

  • 索引鍵必須是有效的 UTF-8 字元字串，長度上限為 128 個字元。金鑰可以是空字串。
  • 值必須是有效的 UTF-8 字元字串，長度上限為 1024 個字元。此值可為空字串。
  • 每個物件最多可有 10 列鍵/值組合。