智能家居设备投放 trait 架构

action.devices.traits.Dispense - 此 trait 适用于支持分发指定数量的一个或多个实体项的设备。

此 trait 还支持分发预设，例如，宠物喂食器的“猫食碗”或水龙头的“玻璃杯”。

设备属性

具有此特征的设备可能会在 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	支持的单位。 支持的值： CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
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	item_name 属性中的项的名称。
amountRemaining	对象	设备中的剩余商品数量。如果设备当前正在分发，此属性会报告剩余金额或设备完成分发后将达到的金额。
amount	编号	剩余金额
unit	String	supported_units 属性中的 amount 的单位。
amountLastDispensed	对象	设备最近一次出售的此商品的数量。如果设备当前正在分发，则此字段应报告当前分发量之前的分发量。
amount	编号	剩余金额
unit	String	supported_units 属性中的 amount 的单位。
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	要分发的商品的名称（来自 item_name 属性）。
amount	编号	必填。 要分发的金额。
unit	String	必填。 amount 的单位（来自 supported_units 属性）。

按预设分配。

参数	类型	说明
presetName	String	必填。 要分发的预设的名称（来自 preset_name 属性）。

不带参数的 Dispense。

参数	类型	说明
没有属性

示例

给我 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 - 当用户必须等待一段时间才能成功取出所请求的商品或数量时（例如，水龙头会出热水，但用户需要等待水加热后才能开始出水）。