智慧型住宅網路控制特徵結構定義

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

裝置屬性

具備這項特徵的裝置可能會回報下列資料： 在 SYNC 作業中使用屬性變更。學習 如要進一步瞭解如何處理 SYNC 意圖，請參閱 意圖執行要求。

屬性 類型 說明
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 意圖，請參閱 意圖執行要求。

州 類型 說明
networkEnabled 布林值

是否已啟用主要網路。
networkSettings 物件

包含主要網路的 SSID。
ssid String

必要。

網路 SSID。
guestNetworkEnabled 布林值

是否已啟用訪客網路。
guestNetworkSettings 物件

包含訪客網路的 SSID。
ssid String

必要。

網路 SSID。
numConnectedDevices 整數

連線至網路的裝置數量。
networkUsageMB Number

網路用量，以 MB 為單位。網路用量仍在目前的帳單週期內，方便您監控帳單週期的網路用量限制。
networkUsageLimitMB Number

網路用量限制，以 MB 為單位。網路用量限制在目前的帳單週期內。
networkUsageUnlimited 布林值

網路用量是否沒有上限。如果設為 True，系統會忽略裝置狀態 networkUsageLimitMB。
lastNetworkDownloadSpeedTest 物件

包含最近網路下載速度測試的結果。
downloadSpeedMbps Number

上次網路速度測試的下載速度，以 Mbps (每秒百萬位元) 為單位。
unixTimestampSec 整數

上次執行網路下載速度測試時的 Unix 時間戳記 (自 Unix 紀元以來經過的秒數)。
status String

指出上次網路下載速度測試是否成功。

支援的值：

SUCCESS
FAILURE
lastNetworkUploadSpeedTest 物件

包含最近網路上傳速度測試的結果。
uploadSpeedMbps Number

上次網路速度測試的上傳速度，以 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 意圖，請參閱 意圖執行要求。

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 可啟用設定檔，否 則停用設定檔。

範例

為孩子關閉網際網路。

{
  "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 作業中持續追蹤回應酬載。學習 如要進一步瞭解如何實作後續回應，請參見 智慧型住宅動作的通知。

酬載包含下列其中一個項目：

成功：networkDownloadSpeedMbps

欄位 類型 說明
followUpToken String

必要。

原始 EXECUTE 要求中提供的權杖。
status String

必要。

要求的結果。

支援的值：

SUCCESS
networkDownloadSpeedMbps Number

必要。

網路下載速度 (以百萬位元/秒為單位)。

成功：networkUploadSpeedMbps

欄位 類型 說明
followUpToken String

必要。

原始 EXECUTE 要求中提供的權杖。
status String

必要。

要求的結果。

支援的值：

SUCCESS
networkUploadSpeedMbps Number

必要。

網路上傳速度 (以百萬位元/秒為單位)。

成功：networkDownloadSpeedMbps 和 networkUploadSpeedMbps

欄位 類型 說明
followUpToken String

必要。

原始 EXECUTE 要求中提供的權杖。
status String

必要。

要求的結果。

支援的值：

SUCCESS
networkDownloadSpeedMbps Number

必要。

網路下載速度 (以百萬位元/秒為單位)。
networkUploadSpeedMbps Number

必要。

網路上傳速度 (以百萬位元/秒為單位)。

失敗

欄位 類型 說明
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