歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。
透過集合功能整理內容 你可以依據偏好儲存及分類內容。

智慧型家用 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 可停用訪客網路。

範例

開啟訪客網路

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

action.devices.commands.EnableDisableNetworkProfile

啟用或停用網路設定檔。必須使用次要使用者 PIN 碼驗證。透過這些指令停用其他安全性裝置時,系統會將使用者的家庭安全視為影響。

這個指令需要下列屬性:
{
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true
}

參數

參數 類型 說明
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 字串

必填。

訪客網路的密碼。

範例

顯示我的訪客 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 字串

必填。

要求的結果。

支援的值:

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