欢迎访问 Google Home 开发者中心，这是了解如何开发智能家居 Action 的新平台。

此页面由 Cloud Translation API 翻译。

智能家居 NetworkControl trait 架构

action.devices.traits.NetworkControl - 此 trait 适用于支持报告网络数据和执行网络专用操作的设备。

设备属性

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

属性	类型	说明
`supportsEnablingGuestNetwork`	布尔值	（默认值：`false`）如果可以启用访客网络，请将其设为 true。
`supportsDisablingGuestNetwork`	布尔值	（默认值：`false`）如果可以停用访客网络，则设为 true。
`supportsGettingGuestNetworkPassword`	布尔值	（默认值：`false`）如果可以通过 `GetGuestNetworkPassword` 命令获取访客网络密码，请将此属性设为 true。
`networkProfiles`	数组	指示支持的网络配置文件名称。
`[item, ...]`	String	表示一组相关设备的网络配置文件的名称。
`supportsEnablingNetworkProfile`	布尔值	（默认值：`"false"`）如果可以启用网络配置文件，则设置为 true。
`supportsDisablingNetworkProfile`	布尔值	（默认值：`"false"`）如果可以停用网络配置文件，则将其设置为 true。
`supportsNetworkDownloadSpeedTest`	布尔值	（默认值：`false`）如果可以运行下载速度测试，则将其设置为 true。
`supportsNetworkUploadSpeedTest`	布尔值	（默认值：`false`）如果可以运行上传速度测试，请将此属性设为 true。

示例

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

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

设备状态

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

州	类型	说明
`networkEnabled`	布尔值	主网络是否已启用。
`networkSettings`	对象	包含主网络的 SSID。
`ssid`	String	必填。网络 SSID。
`guestNetworkEnabled`	布尔值	访客网络是否已启用。
`guestNetworkSettings`	对象	包含访客网络的 SSID。
`ssid`	String	必填。网络 SSID。
`numConnectedDevices`	整数	已连接到网络的设备数量。
`networkUsageMB`	编号	网络流量使用量（以 MB 为单位）。网络流量使用量是在当前结算周期内，这有助于您监控结算周期网络流量使用上限。
`networkUsageLimitMB`	编号	流量使用上限（以 MB 为单位）。流量使用上限是在当前结算周期内。
`networkUsageUnlimited`	布尔值	是否没有流量使用限制。如果此值设为 true，系统会忽略设备状态 networkUsageLimitMB。
`lastNetworkDownloadSpeedTest`	对象	包含最近一次网络下载速度测试的结果。
`downloadSpeedMbps`	编号	上次网络速度测试的下载速度（以兆位每秒 [Mbps] 为单位）。
`unixTimestampSec`	整数	上次运行网络下载速度测试的时间的 Unix 时间戳（自 Unix 纪元起的秒数）。
`status`	String	指示上次网络下载速度测试是成功还是失败。支持的值： `SUCCESS` `FAILURE`
`lastNetworkUploadSpeedTest`	对象	包含最近一次网络上传速度测试的结果。
`uploadSpeedMbps`	编号	上次网络速度测试的上传速度（以兆位每秒 [Mbps] 为单位）。
`unixTimestampSec`	整数	上次运行网络上传速度测试的时间的 Unix 时间戳（自 Unix 纪元起的秒数）。
`status`	String	表示上次网络上传速度测试是成功还是失败。支持的值： `SUCCESS` `FAILURE`
`networkSpeedTestInProgress`	布尔值	（默认值：`false`）当前是否正在运行速度测试。
`networkProfilesState`	对象	网络配置文件的状态。此顶级对象应包含键值对，其中键是 `networkProfiles` 属性中列出的某个网络配置文件的名称，值应为该配置文件的相应状态。
`<string>`	对象	用于存储单个网络配置文件状态的对象。键的值应为 `networkProfiles` 属性中某个网络配置文件的名称。
`enabled`	布尔值	网络配置文件的当前启用/停用状态。

示例

具有有效网络连接的设备。

{
  "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
    }
  }
}

设备命令

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

`action.devices.commands.EnableDisableGuestNetwork`

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

此命令需要以下属性：

{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true
}

参数

参数类型说明

参数	类型	说明
`enable`	布尔值	必填。设为 true 表示启用访客网络，设为 false 表示停用访客网络。

enable

布尔值

必填。

设为 true 表示启用访客网络，设为 false 表示停用访客网络。

示例

开启访客网络。

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

`action.devices.commands.EnableDisableNetworkProfile`

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

此命令需要以下属性：

{
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true
}

参数

参数类型说明

参数	类型	说明
`profile`	String	必填。 `networkProfiles` 属性中的配置文件名称。
`enable`	布尔值	必填。设置为 true 表示启用配置文件，设置为 false 表示停用配置文件。

profile

String

必填。

networkProfiles 属性中的配置文件名称。

enable

布尔值

必填。

设置为 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	必填。访客网络的密码。

guestNetworkPassword

String

必填。

访客网络的密码。

示例

显示我的访客 Wi-Fi 密码。

{
  "guestNetworkPassword": "123456"
}

`action.devices.commands.TestNetworkSpeed`

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

此命令需要以下属性：

{
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true
}

参数

参数类型说明

参数	类型	说明
`testDownloadSpeed`	布尔值	必填。指示是否应测试下载速度。
`testUploadSpeed`	布尔值	必填。指示是否应测试上传速度。
`followUpToken`	String	必填。 Google 提供的用于后续响应的令牌。

testDownloadSpeed

布尔值

必填。

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

testUploadSpeed

布尔值

必填。

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

followUpToken

String

必填。

Google 提供的用于后续响应的令牌。

示例

Wi-Fi 网速怎么样？

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

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

支持的值：

networkSpeedTestInProgress

注意：您无法向此命令发送同步 EXECUTE 响应。对该命令的响应必须通过后续响应发送，且必须采用以下载荷格式。

后续回复

具有此 trait 的设备可能会在 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

必填。

此值可以是此 trait 的任何错误代码，例如 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

智能家居 NetworkControl trait 架构

设备属性

示例

设备状态

示例

设备命令

action.devices.commands.EnableDisableGuestNetwork

参数

示例

action.devices.commands.EnableDisableNetworkProfile

参数

示例

相关错误

action.devices.commands.GetGuestNetworkPassword

参数

示例

结果

示例

action.devices.commands.TestNetworkSpeed

参数

示例

相关错误

后续回复

成功：networkDownloadSpeedMbps

成功：networkUploadSpeedMbps

成功：networkDownloadSpeedMbps 和 networkUploadSpeedMbps

失败

示例

设备错误

`action.devices.commands.EnableDisableGuestNetwork`

`action.devices.commands.EnableDisableNetworkProfile`

`action.devices.commands.GetGuestNetworkPassword`

`action.devices.commands.TestNetworkSpeed`