智慧型家用 NetworkControl 特性結構定義
action.devices.traits.NetworkControl
- 此屬性屬於支援回報網路資料及執行網路專屬作業的裝置。
裝置屬性
具有此特性的裝置可能會在 SYNC
作業中回報下列屬性。如要進一步瞭解如何處理 SYNC
意圖,請參閱意圖執行要求一文。
屬性 | 類型 | 說明 |
---|---|---|
supportsEnablingGuestNetwork |
布林 |
(預設: 如果可以啟用訪客網路,請設為 true。 |
supportsDisablingGuestNetwork |
布林 |
(預設: 如果可以停用訪客網路,請設為 true。 |
supportsGettingGuestNetworkPassword |
布林 |
(預設: 如果可透過 |
networkProfiles |
陣列 |
指出支援的網路設定檔名稱。 |
[item, ...] |
字串 |
代表一組相關裝置的網路設定檔名稱。 |
supportsEnablingNetworkProfile |
布林 |
(預設: 如果可以啟用網路設定檔,請設為 true。 |
supportsDisablingNetworkProfile |
布林 |
(預設: 如果網路設定檔可以停用,請設為 true。 |
supportsNetworkDownloadSpeedTest |
布林 |
(預設: 如果可執行下載速度測試,則設為 true。 |
supportsNetworkUploadSpeedTest |
布林 |
(預設: 如果可執行上傳速度測試,請將值設為 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 |
字串 |
表示上次網路下載速度測試是否成功。 支援的值:
|
lastNetworkUploadSpeedTest |
物件 |
包含最近一次網路上傳速度測試的結果。 |
uploadSpeedMbps |
Number |
上一次網路速度測試的上傳速度 (以每秒 Mbps 為單位)。 |
unixTimestampSec |
整數 |
上次執行網路上傳測試時的 Unix 時間戳記 (自 Unix 紀元時間算起的秒數)。 |
status |
字串 |
表示上次網路上傳速度測試是否成功。 支援的值:
|
networkSpeedTestInProgress |
布林 |
(預設: 目前是否為執行速度測試。 |
networkProfilesState |
物件 |
網路設定檔的狀態。這個頂層物件應包含鍵/值組合,其中鍵是 |
<string> |
物件 |
儲存個別網路設定檔狀態的物件。 |
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 可停用訪客網路。 |
範例
開啟訪客網路。
{ "command": "action.devices.commands.EnableDisableGuestNetwork", "params": { "enable": true } }
action.devices.commands.EnableDisableNetworkProfile
啟用或停用網路設定檔。必須使用次要使用者 PIN 碼驗證。透過這些指令停用其他安全性裝置時,系統會將使用者的家庭安全視為影響。
這個指令需要下列屬性:{ "supportsEnablingNetworkProfile": true, "supportsDisablingNetworkProfile": true }
參數
參數 | 類型 | 說明 |
---|---|---|
profile |
字串 |
必填。
|
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 |
字串 |
必填。 訪客網路的密碼。 |
範例
顯示我的訪客 Wi-Fi 密碼。
{ "guestNetworkPassword": "123456" }
action.devices.commands.TestNetworkSpeed
測試網路下載和上傳速度。
這個指令需要下列屬性:{ "supportsNetworkDownloadSpeedTest": true, "supportsNetworkUploadSpeedTest": true }
參數
參數 | 類型 | 說明 |
---|---|---|
testDownloadSpeed |
布林 |
必填。 指出是否應測試下載速度。 |
testUploadSpeed |
布林 |
必填。 指出是否應測試上傳速度。 |
followUpToken |
字串 |
必填。 Google 提供的後續追蹤權杖。 |
範例
Wi-Fi 的速度是多少?
{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": true, "followUpToken": "123" } }
相關錯誤
嘗試要求執行速度測試時發生錯誤,
支援的值:
networkSpeedTestInProgress
後續回應
具有此特性的裝置可能會透過 EXECUTE
作業傳回下列後續回應酬載。如要進一步瞭解如何執行後續回應,請參閱智慧型住宅動作通知。
酬載包含下列其中一個值:
成功:networkDownloadSpeedMbps
欄位 | 類型 | 說明 |
---|---|---|
followUpToken |
字串 |
必填。 原始 EXECUTE 要求中提供的憑證。 |
status |
字串 |
必填。 要求的結果。 支援的值:
|
networkDownloadSpeedMbps |
Number |
必填。 測量的網路下載速度,單位為百萬位元/秒。 |
成功:networkUploadSpeedMbps
欄位 | 類型 | 說明 |
---|---|---|
followUpToken |
字串 |
必填。 原始 EXECUTE 要求中提供的憑證。 |
status |
字串 |
必填。 要求的結果。 支援的值:
|
networkUploadSpeedMbps |
Number |
必填。 網路上傳速度,單位為百萬位元/秒。 |
成功:networkDownloadSpeedMbps 和 networkUploadSpeedMbps
欄位 | 類型 | 說明 |
---|---|---|
followUpToken |
字串 |
必填。 原始 EXECUTE 要求中提供的憑證。 |
status |
字串 |
必填。 要求的結果。 支援的值:
|
networkDownloadSpeedMbps |
Number |
必填。 測量的網路下載速度,單位為百萬位元/秒。 |
networkUploadSpeedMbps |
Number |
必填。 網路上傳速度,單位為百萬位元/秒。 |
失敗
欄位 | 類型 | 說明 |
---|---|---|
followUpToken |
字串 |
必填。 原始 EXECUTE 要求中提供的憑證。 |
status |
字串 |
必填。 要求的結果。 支援的值:
|
errorCode |
字串 |
必填。 這個值可以是此特性的任何錯誤代碼,例如 |
範例
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