智能家居分配特征架构
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
:用户尝试支付的金额超出了他们在单次查询中可请求的数量。这是为了防止意外分配过多的水分(例如 500,000 杯水)。dispenseAmountBelowLimit
:用户尝试从设备分配商品或金额,但数量低于可分发的最低金额。dispenseFractionalAmountNotSupported
:用户尝试分配设备无法拆分的一定比例的内容(例如,设备是否不能将狗粮等可计数项划分)。genericDispenseNotSupported
:用户尝试从设备进行分配,而不指定商品或预设,但设备不支持此类功能(例如,默认分配操作)。dispenseUnitNotSupported
:用户尝试从具有不受支持的单位(例如,未提供相应商品,因此跳过supported_unit validation
)的设备分配商品。dispenseFractionalUnitNotSupported
:用户尝试分配一定比例的物品,而这种物品可以拆分,但不能是指定的特定单位(例如,水龙头也许可以分配 2.7 杯,但不能分配 2.7 mL)。deviceCurrentlyDispensing
:用户尝试分配商品,但设备已经分配。deviceClogged
:用户尝试分配商品,但设备拥堵。deviceBusy
:用户尝试分配商品,但设备繁忙(一般)。
设备例外情况
在响应的 states
对象中,这些异常可以报告为 exceptionCode
:
amountRemainingLow
- 用户从设备分配商品或金额,使剩余金额较低。您需要负责定义“低”级别。userNeedsToWait
- 当用户必须等待所分配的物品或数量才能成功分配时(例如,水龙头会出水,但用户需要等到水预热后才能开始分配)。