智能家居分发特征架构

action.devices.traits.Dispense - 此特征属于支持分配指定数量的一种或多种实物商品的设备。

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

设备属性

具有此特征的设备可能会在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent，请参阅意图实现。

属性 类型 说明
supportedDispenseItems 数组

包含设备可分配的所有物品的相关信息。
[item, ...] 对象

可舍弃的商品。
item_name String

必填。

分发商品的内部名称。这可能不太方便用户，并且适用于所有语言。
item_name_synonyms 数组

必填。

每种支持的语言中分发的同义词名称。
[item, ...] 对象

所分发商品的同义名称（采用指定语言）。为了提供语言回退，至少需要一个 lang 值为 en 的商品。
synonyms 数组

必填。

配发商品的同义词名称。同义词应同时包含单数和复数形式（如果适用）。此列表中的第一个字符串必须是相应语言中商品的复数形式。
[item, ...] String

同义词名称。为了提供语言回退，至少需要一个 lang 值为 en 的商品。
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 整数

必填。

分配的金额。
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，请参阅意图实现。

州 类型 说明
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 属性中的商品对应。

设备命令

具有此特征的设备可能会响应以下命令，作为 EXECUTE 操作的一部分。如需详细了解如何处理 EXECUTE intent，请参阅意图实现。

action.devices.commands.Dispense

分发商品。

参数

相应载荷包含以下内容之一：

按金额出钞。

参数 类型 说明
item String

要分发的商品的名称，来自 item_name 属性。
amount 编号

必填。

要分配的金额。
unit String

必填。

amount 的单位，来自 supported_units 属性。

按预设量出液。

参数 类型 说明
presetName String

必填。

要从 preset_name 属性中分配的预设的名称。

不带参数的分配。

参数 类型 说明

没有属性

示例

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