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

智能家居 NetworkControl 特征架构

action.devices.traits.NetworkControl - 此特征属于支持报告网络数据和执行网络特定操作的设备。

设备属性

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

属性 类型 说明
supportsEnablingGuestNetwork Boolean

(默认值:false

如果可以启用访客网络,则设置为 true。

supportsDisablingGuestNetwork Boolean

(默认值:false

如果访客网络可以停用,则设置为 true。

supportsGettingGuestNetworkPassword Boolean

(默认值:false

如果可以通过 GetGuestNetworkPassword 命令获取访客网络密码,则设为 true。

networkProfiles 数组

表示支持的网络配置文件名称。

[item, ...] String

表示一组相关设备的网络配置文件的名称。

supportsEnablingNetworkProfile Boolean

(默认值:"false"

如果可以启用网络配置文件,则设置为 true。

supportsDisablingNetworkProfile Boolean

(默认值:"false"

如果可以停用网络配置文件,则设置为 true。

supportsNetworkDownloadSpeedTest Boolean

(默认值:false

如果可以运行下载速度测试,则设置为 true。

supportsNetworkUploadSpeedTest Boolean

(默认值:false

如果可以运行上传速度测试,则设置为 true。

示例

支持访客网络、配置文件和速度测试的网络设备。

{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true,
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true,
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true,
  "supportsGettingGuestNetworkPassword": true,
  "networkProfiles": [
    "Kids"
  ]
}

设备状态

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

类型 说明
networkEnabled Boolean

主网络是否已启用。

networkSettings 对象

包含主网络的 SSID。

ssid String

必填。

网络 SSID。

guestNetworkEnabled Boolean

访客网络是否已启用。

guestNetworkSettings 对象

包含客户机网络的 SSID。

ssid String

必填。

网络 SSID。

numConnectedDevices 整数

连接到网络的设备数量。

networkUsageMB 编号

网络用量(以 MB 为单位)。网络用量处于当前结算周期内,这对于监控某个结算周期内的网络用量限额非常有用。

networkUsageLimitMB 编号

网络用量上限 (MB)。网络用量限额在当前结算周期内。

networkUsageUnlimited Boolean

网络使用量是否不受限制。如果将其设置为 true,则会忽略设备状态 networkUsageLimitMB。

lastNetworkDownloadSpeedTest 对象

包含最近一次网络下载速度测试的结果。

downloadSpeedMbps 编号

上次网速测试的下载速度(以 Mbps 为单位)。

unixTimestampSec 整数

上次运行网络下载速度测试时的 Unix 时间戳(与 Unix 计时原点之间相隔的秒数)。

status String

指明上一次网络下载速度测试是成功还是失败。

支持的值:

SUCCESS
FAILURE
lastNetworkUploadSpeedTest 对象

包含最近一次网络上传速度测试的结果。

uploadSpeedMbps 编号

上次网速测试的上传速度(以 Mbps 为单位)。

unixTimestampSec 整数

上次运行网络上传速度测试时的 Unix 时间戳(与 Unix 计时原点之间相隔的秒数)。

status String

指明上一次网络上传速度测试是成功还是失败。

支持的值:

SUCCESS
FAILURE
networkSpeedTestInProgress Boolean

(默认值:false

当前是否正在运行速度测试。

networkProfilesState 对象

网络配置文件的状态。此顶级对象应包含键值对,其中,键是 networkProfiles 属性中列出的其中一个网络配置文件的名称,而值应为该配置文件的相应状态。

<string> 对象

用于存储单个网络配置文件的状态的对象。 键的值应该是 networkProfiles 属性中某个网络配置文件的名称。

enabled Boolean

网络配置文件当前的启用/停用状态。

示例

具有活跃网络的设备

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8
}

具有活跃网络和速度测试结果的设备

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8,
  "lastNetworkDownloadSpeedTest": {
    "downloadSpeedMbps": 159.8,
    "unixTimestampSec": 1563215576,
    "status": "SUCCESS"
  },
  "lastNetworkUploadSpeedTest": {
    "uploadSpeedMbps": 64.1,
    "unixTimestampSec": 1563215576,
    "status": "SUCCESS"
  }
}

具有正在进行中的网络和速度测试的设备。

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8,
  "networkSpeedTestInProgress": true
}

已停用“kids”networkProfile 的设备。

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "networkProfilesState": {
    "parents": {
      "enabled": true
    },
    "kids": {
      "enabled": false
    }
  }
}

设备命令

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

action.devices.commands.EnableDisableGuestNetwork

启用或停用访客网络。必须使用 PIN 码进行第二层用户身份验证。如果通过这些命令停用了其他安全设备,用户的住宅安全可能会被视为受影响。

此命令需要以下特性:
{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true
}

参数

参数 类型 说明
enable Boolean

必填。

如果为 true,则启用访客网络;如果设置为 false,则会停用访客网络。

示例

开启访客网络

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

action.devices.commands.EnableDisableNetworkProfile

启用或停用网络配置文件。必须使用 PIN 码进行第二层用户身份验证。如果通过这些命令停用了其他安全设备,用户的住宅安全可能会被视为受影响。

此命令需要以下特性:
{
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true
}

参数

参数 类型 说明
profile String

必填。

来自 networkProfiles 属性的个人资料名称。

enable Boolean

必填。

True 启用配置文件,False 停用配置文件。

示例

为孩子关闭网络

{
  "command": "action.devices.commands.EnableDisableNetworkProfile",
  "params": {
    "profile": "Kids",
    "enable": false
  }
}

尝试控制给定的网络配置文件时出错。

支持的值:

networkProfileNotRecognized

action.devices.commands.GetGuestNetworkPassword

获取访客网络密码。必须使用 PIN 码进行第二层用户身份验证。如果通过这些命令停用了其他安全设备,用户的住宅安全可能会被视为受影响。

此命令需要以下特性:
{
  "supportsGettingGuestNetworkPassword": true
}

参数

参数 类型 说明

没有属性

示例

显示我的访客 Wi-Fi 密码

{
  "command": "action.devices.commands.GetGuestNetworkPassword",
  "params": {}
}

成效

成效 类型 说明
guestNetworkPassword String

必填。

访客网络的密码。

示例

显示我的访客 Wi-Fi 密码

{
  "guestNetworkPassword": "123456"
}

action.devices.commands.TestNetworkSpeed

测试网络下载和上传速度。

此命令需要以下特性:
{
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true
}

参数

参数 类型 说明
testDownloadSpeed Boolean

必填。

指明是否应测试下载速度。

testUploadSpeed Boolean

必填。

指明是否应测试上传速度。

followUpToken String

必填。

Google 提供的用于跟进响应的令牌。

示例

什么是 Wi-Fi 网速?

{
  "command": "action.devices.commands.TestNetworkSpeed",
  "params": {
    "testDownloadSpeed": true,
    "testUploadSpeed": true,
    "followUpToken": "123"
  }
}

尝试请求速度测试时出错。

支持的值:

networkSpeedTestInProgress

跟进回复

具有此特征的设备可能会在 EXECUTE 操作中返回以下后续响应载荷。如需详细了解如何实现后续响应,请参阅智能家居 Action 通知

载荷包含以下其中一项:

成功:networkDownloadSpeedMbps

字段 类型 说明
followUpToken String

必填。

原始 EXECUTE 请求中提供的令牌。

status String

必填。

请求的结果。

支持的值:

SUCCESS
networkDownloadSpeedMbps 编号

必填。

网络下载速度,以兆比特每秒为单位进行测量。

成功:networkUploadSpeedMbps

字段 类型 说明
followUpToken String

必填。

原始 EXECUTE 请求中提供的令牌。

status String

必填。

请求的结果。

支持的值:

SUCCESS
networkUploadSpeedMbps 编号

必填。

网络上传速度,以兆比特每秒为单位。

成功:networkDownloadSpeedMbps 和 networkUploadSpeedMbps

字段 类型 说明
followUpToken String

必填。

原始 EXECUTE 请求中提供的令牌。

status String

必填。

请求的结果。

支持的值:

SUCCESS
networkDownloadSpeedMbps 编号

必填。

网络下载速度,以兆比特每秒为单位进行测量。

networkUploadSpeedMbps 编号

必填。

网络上传速度,以兆比特每秒为单位。

失败

字段 类型 说明
followUpToken String

必填。

原始 EXECUTE 请求中提供的令牌。

status String

必填。

请求的结果。

支持的值:

FAILURE
errorCode String

必填。

该值可以是此特征的任何错误代码,例如 transientError

示例

什么是 Wi-Fi 网速?(跟进回复)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "SUCCESS",
      "networkDownloadSpeedMbps": 23.3,
      "networkUploadSpeedMbps": 10.2,
      "followUpToken": "1234"
    }
  }
}

什么是 Wi-Fi 网速?(失败的跟进响应)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "FAILURE",
      "errorCode": "transientError",
      "followUpToken": "1234"
    }
  }
}

设备出错

查看错误和异常的完整列表。

尝试控制给定的网络配置文件时出错。

支持的值:

networkProfileNotRecognized

尝试请求速度测试时出错。

支持的值:

networkSpeedTestInProgress