本頁面由 Cloud Translation API 翻譯而成。

智慧型家用 NetworkControl 特性結構定義

action.devices.traits.NetworkControl - 此屬性屬於支援回報網路資料及執行網路專屬作業的裝置。

裝置屬性

具有此特性的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖，請參閱意圖執行要求一文。

屬性	類型	說明
`supportsEnablingGuestNetwork`	布林	(預設：`false`) 如果可以啟用訪客網路，請設為 true。
`supportsDisablingGuestNetwork`	布林	(預設：`false`) 如果可以停用訪客網路，請設為 true。
`supportsGettingGuestNetworkPassword`	布林	(預設：`false`) 如果可透過 `GetGuestNetworkPassword` 指令取得訪客網路密碼，則設為 true。
`networkProfiles`	陣列	指出支援的網路設定檔名稱。
`[item, ...]`	字串	代表一組相關裝置的網路設定檔名稱。
`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"
  ]
}

裝置狀態：STATE

具有此特性的實體可能會在 QUERY 作業中回報下列狀態。如要進一步瞭解如何處理 QUERY 意圖，請參閱意圖執行要求一文。

州	類型	說明
`networkEnabled`	布林	是否啟用主要網路。
`networkSettings`	物件	包含主要網路的 SSID。
`ssid`	字串	必填。網路 SSID。
`guestNetworkEnabled`	布林	是否已啟用訪客網路。
`guestNetworkSettings`	物件	包含訪客網路的 SSID。
`ssid`	字串	必填。網路 SSID。
`numConnectedDevices`	整數	已連上網路的裝置數量。
`networkUsageMB`	Number	網路用量 (MB)。目前的用量屬於目前的帳單週期內，方便您根據帳單週期的用量限制進行監控。
`networkUsageLimitMB`	Number	網路用量限制 (MB)。網路用量在目前的帳單週期內。
`networkUsageUnlimited`	布林	網路用量沒有限制。如果設為 True，系統會忽略裝置狀態 networkUsageLimitMB。
`lastNetworkDownloadSpeedTest`	物件	包含最近網路下載速度測試結果。
`downloadSpeedMbps`	Number	上一次網路速度測試的下載速度 (以每秒 Mbps 為單位)。
`unixTimestampSec`	整數	上次執行網路下載速度測試的 Unix 時間戳記 (自 Unix 紀元時間算起的秒數)。
`status`	字串	表示上次網路下載速度測試是否成功。支援的值： `SUCCESS` `FAILURE`
`lastNetworkUploadSpeedTest`	物件	包含最近一次網路上傳速度測試的結果。
`uploadSpeedMbps`	Number	上一次網路速度測試的上傳速度 (以每秒 Mbps 為單位)。
`unixTimestampSec`	整數	上次執行網路上傳測試時的 Unix 時間戳記 (自 Unix 紀元時間算起的秒數)。
`status`	字串	表示上次網路上傳速度測試是否成功。支援的值： `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
    }
  }
}

裝置指令

具有此特性的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖，請參閱意圖執行要求一文。

`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`	字串	必填。 `networkProfiles` 屬性中的設定檔名稱。
`enable`	布林	必填。設為 True 可啟用設定檔，設為 False 可停用設定檔。

profile

字串

必填。

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`	字串	必填。訪客網路的密碼。

guestNetworkPassword

字串

必填。

訪客網路的密碼。

範例

顯示我的訪客 Wi-Fi 密碼。

{
  "guestNetworkPassword": "123456"
}

`action.devices.commands.TestNetworkSpeed`

測試網路下載和上傳速度。

這個指令需要下列屬性：

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

參數

參數類型說明

參數	類型	說明
`testDownloadSpeed`	布林	必填。指出是否應測試下載速度。
`testUploadSpeed`	布林	必填。指出是否應測試上傳速度。
`followUpToken`	字串	必填。 Google 提供的後續追蹤權杖。

testDownloadSpeed

布林

必填。

指出是否應測試下載速度。

testUploadSpeed

布林

必填。

指出是否應測試上傳速度。

followUpToken

字串

必填。

Google 提供的後續追蹤權杖。

範例

Wi-Fi 的速度是多少？

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

嘗試要求執行速度測試時發生錯誤，

支援的值：

networkSpeedTestInProgress

注意：您無法向這個指令傳送同步 EXECUTE 回應。必須使用以下酬載格式，透過後續回應傳送對指令的回應。

後續回應

具有此特性的裝置可能會透過 EXECUTE 作業傳回下列後續回應酬載。如要進一步瞭解如何執行後續回應，請參閱智慧型住宅動作通知。

酬載包含下列其中一個值：

成功：networkDownloadSpeedMbps

欄位類型說明

followUpToken

字串

必填。

原始 EXECUTE 要求中提供的憑證。

status

字串

必填。

要求的結果。

支援的值：

SUCCESS

networkDownloadSpeedMbps

Number

必填。

測量的網路下載速度，單位為百萬位元/秒。

成功：networkUploadSpeedMbps

欄位類型說明

followUpToken

字串

必填。

原始 EXECUTE 要求中提供的憑證。

status

字串

必填。

要求的結果。

支援的值：

SUCCESS

networkUploadSpeedMbps

Number

必填。

網路上傳速度，單位為百萬位元/秒。

成功：networkDownloadSpeedMbps 和 networkUploadSpeedMbps

欄位	類型	說明
`followUpToken`	字串	必填。原始 EXECUTE 要求中提供的憑證。
`status`	字串	必填。要求的結果。支援的值： `SUCCESS`
`networkDownloadSpeedMbps`	Number	必填。測量的網路下載速度，單位為百萬位元/秒。
`networkUploadSpeedMbps`	Number	必填。網路上傳速度，單位為百萬位元/秒。

失敗

欄位類型說明

followUpToken

字串

必填。

原始 EXECUTE 要求中提供的憑證。

status

字串

必填。

要求的結果。

支援的值：

FAILURE

errorCode

字串

必填。

這個值可以是此特性的任何錯誤代碼，例如 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"
    }
  }
}

裝置錯誤：ERRORS

請參閱錯誤和例外狀況的完整清單。

嘗試控制指定網路設定檔時發生錯誤。

支援的值：

networkProfileNotRecognized

嘗試要求執行速度測試時發生錯誤，

支援的值：

networkSpeedTestInProgress

智慧型家用 NetworkControl 特性結構定義

裝置屬性

範例

裝置狀態：STATE

範例

裝置指令

action.devices.commands.EnableDisableGuestNetwork

參數

範例

action.devices.commands.EnableDisableNetworkProfile

參數

範例

相關錯誤

action.devices.commands.GetGuestNetworkPassword

參數

範例

結果

範例

action.devices.commands.TestNetworkSpeed

參數

範例

相關錯誤

後續回應

成功：networkDownloadSpeedMbps

成功：networkUploadSpeedMbps

成功：networkDownloadSpeedMbps 和 networkUploadSpeedMbps

失敗

範例

裝置錯誤：ERRORS

`action.devices.commands.EnableDisableGuestNetwork`

`action.devices.commands.EnableDisableNetworkProfile`

`action.devices.commands.GetGuestNetworkPassword`

`action.devices.commands.TestNetworkSpeed`