智能家居 NetworkControl 特征架构

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

设备属性

具有此特征的设备可能会报告以下内容 作为 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"
  ]
}

设备状态

具有此特征的实体可能会报告以下内容 QUERY 操作包含的指定状态。学习内容 有关处理 QUERY intent 的更多信息，请参阅 intent 执行方式。

州 类型 说明
networkEnabled 布尔值

主网络是否已启用。
networkSettings 对象

包含主网络的 SSID。
ssid String

必填。

网络 SSID。
guestNetworkEnabled 布尔值

访客网络是否已启用。
guestNetworkSettings 对象

包含访客网络的 SSID。
ssid String

必填。

网络 SSID。
numConnectedDevices 整数

连接到网络的设备数量。
networkUsageMB 编号

以 MB (MB) 为单位的网络使用情况。当前结算周期内的网络使用量，相对于结算周期内的网络使用量限制而言，您可以监控流量消耗情况。
networkUsageLimitMB 编号

以 MB (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
}

包含“儿童”的设备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 布尔值

必填。

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 表示停用配置文件。

示例

为孩子关闭互联网。

{
  "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 布尔值

必填。

指示是否应测试下载速度。
testUploadSpeed 布尔值

必填。

指明是否应测试上传速度。
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 编号

必填。

网络下载速度（以 MB/秒为单位）。

成功：networkUploadSpeedMbps

字段 类型 说明
followUpToken String

必填。

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

必填。

请求的结果。

支持的值：

SUCCESS
networkUploadSpeedMbps 编号

必填。

以 MB/秒为单位的网络上传速度。

成功：networkDownloadSpeedMbps 和 networkUploadSpeedMbps

字段 类型 说明
followUpToken String

必填。

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

必填。

请求的结果。

支持的值：

SUCCESS
networkDownloadSpeedMbps 编号

必填。

网络下载速度（以 MB/秒为单位）。
networkUploadSpeedMbps 编号

必填。

以 MB/秒为单位的网络上传速度。

失败

字段 类型 说明
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