欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。
使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

智能家居分配特征架构

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

支持的单位。

支持的值:

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,请参阅 intent 执行方式

类型 说明
dispenseItems 数组

设备可以分配的商品的状态。

[item, ...] 对象

给定项的状态。

itemName String

item_name 属性中的商品名称。

amountRemaining 对象

设备中剩余的内容量。如果设备目前正在进行分配,这会报告剩余金额或设备完成分配后的金额。

amount 编号

剩余金额

unit String

supported_units 属性中的 amount 的单位。

amountLastDispensed 对象

设备最近分配的商品量。如果设备正在分配,则应在当前分配之前报告分配的金额。

amount 编号

剩余金额

unit String

supported_units 属性中的 amount 的单位。

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
    }
  ]
}

只需使用一种度量单位报告 amountRemainingamountLastDispensed

可以在 dispenseItems 数组中提供多个项。每个项的名称必须是唯一的,并且必须与 supportedDispenseItems 属性中的项相对应。

设备命令

具有此特征的设备可能会在 EXECUTE 操作中响应以下命令。如需详细了解如何处理 EXECUTE intent,请参阅 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 mL)。
  • deviceCurrentlyDispensing:用户尝试分配商品,但设备已经开始分配。
  • deviceClogged:用户尝试分配商品,但设备卡住了。
  • deviceBusy:用户尝试分配商品,但设备繁忙(通用)。

设备例外情况

这些异常可以报告为响应的 states 对象中的 exceptionCode

  • amountRemainingLow - 用户从设备上分配商品或金额,将剩余金额调低。您负责定义哪些属于“低”级别。
  • userNeedsToWait - 用户必须等待,才能成功分配要求的物品或数量(例如,水龙头将分配热水,但用户需要等到水变热后才能开始分配)。