智能家居设备投放 trait 架构
action.devices.traits.Dispense
- 此 trait 属于支持分配指定数量的一种或多种实体物品的设备。
此特征还支持分配预设值,例如为宠物喂食器分配“猫粮碗”,或为水龙头分配“杯子”。
设备属性
具有此 trait 的设备可能会在 SYNC
操作中报告以下属性。如需详细了解如何处理 SYNC
intent,请参阅intent 执行方式。
属性 | 类型 | 说明 |
---|---|---|
supportedDispenseItems |
数组 |
包含设备可以分发的所有商品的相关信息。 |
[item, ...] |
对象 |
可舍弃的商品。 |
item_name |
String |
必填。 所分发商品的内部名称。这可能不利于用户,并且会在所有语言版本中共享。 |
item_name_synonyms |
数组 |
必填。 每种受支持语言的 dispensed 的同义词名称。 |
[item, ...] |
对象 |
已投喂商品以指定语言显示的同义词名称。 |
synonyms |
数组 |
必填。 已投放的商品的同义词名称。同义词应同时包含单数和复数形式(如果适用)。此列表中的第一个字符串必须是相应语言的对应商品的复数形式。 |
[item, ...] |
String |
同义词名称 |
lang |
String |
必填。 语言代码 (ISO 639-1)。请参阅支持的语言。 |
supported_units |
数组 |
必填。 设备针对该项支持的一组单位。 |
[item, ...] |
String |
支持的单位。 支持的值:
|
default_portion |
对象 |
必填。 可能分发的商品的典型数量。 |
amount |
整数 |
必填。 dispensed amount。 |
unit |
String |
必填。 分发单位。 |
supportedDispensePresets |
数组 |
设备支持的预设。 |
[item, ...] |
对象 |
预设。 |
preset_name |
String |
必填。 预设的内部名称。此名称可能不方便用户使用,并且会在所有语言之间共享。 |
preset_name_synonyms |
数组 |
必填。 预设在每种受支持语言的同义词名称。 |
[item, ...] |
对象 |
指定语言中预设的近义词名称。 |
synonyms |
数组 |
必填。 预设的别名名称。同义词应同时包含单数和复数形式(如果适用)。 |
[item, ...] |
String |
同义词名称 |
lang |
String |
必填。 语言代码 (ISO 639-1)。请参阅支持的语言。 |
示例
支持预设的液体单位的饮水机。
{ "supportedDispenseItems": [ { "item_name": "Water", "item_name_synonyms": [ { "lang": "en", "synonyms": [ "Water" ] } ], "supported_units": [ "TEASPOONS", "TABLESPOONS", "FLUID_OUNCES", "CUPS", "PINTS", "QUARTS", "GALLONS", "MILLILITERS", "LITERS", "DECILITERS" ], "default_portion": { "amount": 2, "unit": "CUPS" } } ], "supportedDispensePresets": [ { "preset_name": "cat_bowl", "preset_name_synonyms": [ { "lang": "en", "synonyms": [ "Cat water bowl", "Cat water dish", "Cat water cup" ] } ] }, { "preset_name": "glass_1", "preset_name_synonyms": [ { "lang": "en", "synonyms": [ "Glass of water", "Glass" ] } ] } ] }
无预设的宠物食品分配器。
{ "supportedDispenseItems": [ { "item_name": "Treat", "item_name_synonyms": [ { "lang": "en", "synonyms": [ "Treats", "Dog treats", "Treat", "Dog treat" ] } ], "supported_units": [ "NO_UNITS" ], "default_portion": { "amount": 1, "unit": "NO_UNITS" } } ] }
设备状态
具有此特征的实体可能会在 QUERY
操作中报告以下状态。如需详细了解如何处理 QUERY
intent,请参阅 intent 执行方式。
州 | 类型 | 说明 |
---|---|---|
dispenseItems |
数组 |
设备可以分配的物品的状态。 |
[item, ...] |
对象 |
给定项的状态。 |
itemName |
String |
|
amountRemaining |
对象 |
设备中相应内容的剩余量。如果设备目前正在分配,则系统会报告剩余的分配量或设备完成分配后的金额。 |
amount |
编号 |
剩余金额 |
unit |
String |
|
amountLastDispensed |
对象 |
设备最近一次出售的此商品的数量。如果设备当前正在分发,则此字段应报告当前分发量之前的分发量。 |
amount |
编号 |
剩余金额 |
unit |
String |
|
isCurrentlyDispensing |
布尔值 |
指示设备当前是否正在分发此商品。 |
示例
我的饮水机中还剩多少狗粮?
{ "dispenseItems": [ { "itemName": "Dog treats", "amountRemaining": { "amount": 83, "unit": "NO_UNITS" }, "amountLastDispensed": { "amount": 2, "unit": "NO_UNITS" }, "isCurrentlyDispensing": false } ] }
我的饮水机中还剩多少水?
{ "dispenseItems": [ { "itemName": "Water", "amountRemaining": { "amount": 6.2, "unit": "GALLONS" }, "amountLastDispensed": { "amount": 1, "unit": "CUPS" }, "isCurrentlyDispensing": false } ] }
我之前喂了多少猫粮?
{ "dispenseItems": [ { "itemName": "cat_food", "amountRemaining": { "amount": 16.5, "unit": "CUPS" }, "amountLastDispensed": { "amount": 2.5, "unit": "CUPS" }, "isCurrentlyDispensing": false } ] }
水龙头是否仍在出水?
{ "dispenseItems": [ { "itemName": "Water", "isCurrentlyDispensing": true } ] }
amountRemaining
和 amountLastDispensed
只需使用一种计量单位进行报告。
dispenseItems
数组中可以提供多个项。
每个项名称都必须是唯一的,并且必须与 supportedDispenseItems
属性中的项相对应。
设备命令
具有此 trait 的设备可能会在 EXECUTE
操作期间响应以下命令。如需详细了解如何处理 EXECUTE
intent,请参阅 intent 执行方式。
action.devices.commands.Dispense
分发商品。
参数
载荷包含以下任一内容:
按金额分发。
参数 | 类型 | 说明 |
---|---|---|
item |
String |
要分发的商品的名称(来自 |
amount |
编号 |
必填。 要分发的金额。 |
unit |
String |
必填。
|
按预设值分配。
参数 | 类型 | 说明 |
---|---|---|
presetName |
String |
必填。 要分配的预设名称,来自 |
不使用参数进行分配。
参数 | 类型 | 说明 |
---|---|---|
没有属性 |
示例
给我 1 杯水。
{ "command": "action.devices.commands.Dispense", "params": { "amount": 1, "unit": "CUPS", "item": "Water" } }
给猫咪水碗加满水。
{ "command": "action.devices.commands.Dispense", "params": { "presetName": "cat_bowl" } }
出水。
{ "command": "action.devices.commands.Dispense", "params": {} }
设备错误
查看错误和异常的完整列表。dispenseAmountRemainingExceeded
:用户尝试从剩余金额不足的设备中取出商品或金额。dispenseAmountAboveLimit
:用户尝试提取的金额超出了单次查询中可请求的金额上限。这是为了防止意外分发过多量水(例如 50 万杯水)。dispenseAmountBelowLimit
:用户尝试从设备中分发的商品或数量低于设备可分发的最低数量。dispenseFractionalAmountNotSupported
:用户尝试分配数量不能由设备拆分的物品(例如,狗粮等可数项可能无法被设备整除)。genericDispenseNotSupported
:用户尝试从设备中取出物品,但未指定物品或预设,但设备不支持此类功能(例如默认的取出操作)。dispenseUnitNotSupported
:用户尝试从不支持相应用例的设备中分发内容(例如,未提供相应项,因此跳过了supported_unit validation
)。dispenseFractionalUnitNotSupported
:用户尝试分次取出可分割的商品,但不是以指定的特定单位(例如,水龙头可以分次取出 2.7 杯,但不能分次取出 2.7 毫升)。deviceCurrentlyDispensing
:用户尝试分配商品,但设备已在分配。deviceClogged
:用户尝试取出物品,但设备堵塞了。deviceBusy
:用户尝试分发商品,但设备正忙(通用)。
设备例外情况
您可以在响应的 states
对象中将这些异常报告为 exceptionCode
:
amountRemainingLow
- 用户从设备中分配某个商品或金额,使剩余金额降至较低水平。您负责定义“低”级别的含义。userNeedsToWait
- 当用户必须等待一段时间才能成功取出所请求的商品或数量时(例如,水龙头会出热水,但用户需要等待水加热后才能开始出水)。