智能家居分配特征架构
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 |
必填。 要分配的预设的名称,来自 |
不带参数的分配。
参数 | 类型 | 说明 |
---|---|---|
没有属性 |
示例
给我一杯水。
{ "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
- 用户必须等待才能成功分配所请求商品或饮水量(例如,水龙头将出热水,但用户需要等待水升温后才会开始饮水)。