智能家居分配特征架构
action.devices.traits.Dispense
- 此特征属于支持分配指定数量的一个或多个实体物品的设备。
此特征还支持分配预设,例如为宠物喂食器分配“猫食盆”,或为龙头分配“玻璃杯”。
设备属性
具有此特征的设备可能会在 SYNC
操作中报告以下属性。如需详细了解如何处理 SYNC
intent,请参阅 intent 执行方式。
属性 | 类型 | 说明 |
---|---|---|
supportedDispenseItems |
数组 |
包含设备可以分配的所有项目的相关信息。 |
[item, ...] |
对象 |
可分配的商品。 |
item_name |
String |
必填。 已分配商品的内部名称。这种格式对用户不友好,并且适用于所有语言。 |
item_name_synonyms |
数组 |
必填。 以各种受支持的语言分配的同义词。 |
[item, ...] |
对象 |
指定语言的已分配商品的同义词名称。 |
synonyms |
数组 |
必填。 所分配项的同义词名称。同义词应包括单复数形式(如果适用)。此列表中的第一个字符串必须是该项目所用语言的复数形式。 |
[item, ...] |
String |
同义词 |
lang |
String |
必填。 语言代码 (ISO 639-1)。请参阅支持的语言。 |
supported_units |
数组 |
必填。 设备针对该内容支持的单位集。 |
[item, ...] |
String |
支持的单位。 支持的值:
|
default_portion |
对象 |
必填。 通常可发放的商品金额。 |
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 |
Boolean |
指示设备目前是否正在分发此商品。 |
示例
我的分配器中还有多少狗粮?
{ "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
属性中的项相对应。
设备命令
具有此特征的设备可能会在 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 mL)。deviceCurrentlyDispensing
:用户尝试分配商品,但设备已经开始分配。deviceClogged
:用户尝试分配商品,但设备卡住了。deviceBusy
:用户尝试分配商品,但设备繁忙(通用)。
设备例外情况
这些异常可以报告为响应的 states
对象中的 exceptionCode
:
amountRemainingLow
- 用户从设备上分配商品或金额,将剩余金额调低。您负责定义哪些属于“低”级别。userNeedsToWait
- 用户必须等待,才能成功分配要求的物品或数量(例如,水龙头将分配热水,但用户需要等到水变热后才能开始分配)。