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

智能家居音量特征架构

action.devices.traits.Volume - 此特征属于能更改音量的设备(例如,将音量设为特定级别、静音或取消静音)。

设备属性

具有此特征的设备可能会在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent,请参阅 intent 执行方式

属性 类型 说明
volumeMaxLevel 整数

必填。

最大音量,假设基线为 0(静音)。Google 助理会相应地调整动词命令(例如“调高电视的音量”)。

volumeCanMuteAndUnmute Boolean

必填。

指示设备是否可以将音量静音和取消静音。“静音”是一个单独的选项,因为“静音”行为会将音量设为 0,同时记住上一个音量,因此“取消静音”功能可以将其恢复。这反映在音量状态下 - 如果音量为 5,并且用户设为静音,音量仍为 5 且 isMuted 为 true。

volumeDefaultPercentage 整数

(默认值:40

用户或制造商定义的默认音量(以百分比表示)。比例值必须介于 0-100 之间。

levelStepSize 整数

(默认值:1

相对音量查询(例如“<device_name>上的音量调高”)的默认步长。

commandOnlyVolume Boolean

(默认值:false

指明设备是否使用单向 (true) 或双向 (false) 通信。例如,如果控制器可以在发送请求后确认新设备状态,则此字段为 false。如果无法确认请求是否成功执行或获取设备的状态(例如,如果设备是传统红外线遥控器),则将此字段设置为 true。

示例

可以设为静音并报告当前状态的扬声器设备

{
  "volumeMaxLevel": 11,
  "volumeCanMuteAndUnmute": true,
  "levelStepSize": 2,
  "commandOnlyVolume": false,
  "volumeDefaultPercentage": 6
}

设备状态

具有此特征的实体可能会在 QUERY 操作中报告以下状态。如需详细了解如何处理 QUERY intent,请参阅 intent 执行方式

类型 说明
currentVolume 整数

必填。

当前的音量百分比。该值必须介于 >0volumeMaxLevel 之间。

isMuted Boolean

如果 volumeCanMuteAndUnmute 属性设为 true,则必须提供此属性。如果设备已设为静音,则为 true;否则为 false。如果 isMuted 为 true,设备仍会为记住的点返回 currentVolume

示例

可以设为静音并报告当前状态的扬声器设备

{
  "currentVolume": 5,
  "isMuted": false
}

设备命令

具有此特征的设备可能会在 EXECUTE 操作中响应以下命令。如需详细了解如何处理 EXECUTE intent,请参阅 intent 执行方式

action.devices.commands.mute

将设备静音或取消静音。

参数

参数 类型 说明
mute Boolean

必填。

是将设备设为静音还是取消静音。

示例

将音响设备静音

{
  "command": "action.devices.commands.mute",
  "params": {
    "mute": true
  }
}

action.devices.commands.setVolume

根据 volumeMaxLevel 将音量设置为请求的音量。

参数

参数 类型 说明
volumeLevel 整数

必填。

新卷,从 0volumeMaxLevel

示例

设置音响设备的绝对音量

{
  "command": "action.devices.commands.setVolume",
  "params": {
    "volumeLevel": 6
  }
}

action.devices.commands.volumeRelative

根据 volumeMaxLevel 设置音量调高或调低 n 步。对于使用相对缩放比例的指令,Google 助理会适当地选择 n 来缩放到可用步骤。例如,与将电视调大一点相比,将电视调大一点会设置更高的步数。

参数

参数 类型 说明
relativeSteps 整数

必填。

“减”为负。

示例

在纯命令模式下设置音响设备的相对音量

{
  "command": "action.devices.commands.volumeRelative",
  "params": {
    "relativeSteps": -1
  }
}

设备出错

查看错误和异常的完整列表。
  • volumeAlreadyMax:当设备已经达到最大音量时,该设备会收到 VolumeUp 命令。
  • volumeAlreadyMin:当设备处于最低音量时,该设备会收到 VolumeDown 命令。