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

智慧型住宅音量音量結構定義

action.devices.traits.Volume - 這個特質屬於可以調整音量的裝置 (例如將音量設為特定等級、靜音或取消靜音)。

裝置屬性

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

屬性 類型 說明
volumeMaxLevel 整數

必填。

最大音量等級 (假設基準為 0 (靜音)。Google 助理會據此調整副詞指令 (例如「讓電視更大聲」)。

volumeCanMuteAndUnmute 布林

必填。

指出裝置是否可以設為靜音及取消靜音。「靜音」是另外的選擇,因為「靜音」行為會將音量設定為 0,同時記住先前的音量,以便取消靜音。這反映的是磁碟區狀態 - 如果音量為 5,而使用者將音量設為靜音,音量則會保持 5,而 isMuted 為 true。

volumeDefaultPercentage 整數

(預設:40)

使用者或製造商定義的預設音量音量 (百分比)。比例範圍必須為 0-100。

levelStepSize 整數

(預設:1)

相關音量查詢的預設步驟大小,例如「在 <裝置名稱> 上調高音量」。

commandOnlyVolume 布林

(預設:false)

指出裝置是否使用單向 (true) 或雙向 (false) 通訊。舉例來說,如果控制器在傳送要求後可確認新裝置狀態,這個欄位就會是 false。如果無法確認要求是否成功執行或取得裝置狀態 (例如裝置是傳統紅外線遙控器),請將這個欄位設為 true。

範例

可設為靜音並回報目前狀態的揚聲器裝置

{
  "volumeMaxLevel": 11,
  "volumeCanMuteAndUnmute": true,
  "levelStepSize": 2,
  "commandOnlyVolume": false,
  "volumeDefaultPercentage": 6
}

裝置狀態:STATE

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

類型 說明
currentVolume 整數

必填。

目前的音量百分比。這個值必須介於 >0volumeMaxLevel 之間。

isMuted 布林

如果 volumeCanMuteAndUnmute 屬性設為 true,則為必要屬性。裝置設為靜音時傳回 True,否則為 False。如果 isMuted 為 true,裝置仍會針對記憶點傳回 currentVolume

範例

可設為靜音並回報目前狀態的揚聲器裝置

{
  "currentVolume": 5,
  "isMuted": false
}

裝置指令

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

action.devices.commands.mute

將裝置靜音或取消靜音。

參數

參數 類型 說明
mute 布林

必填。

是否將裝置靜音或取消靜音。

範例

將喇叭裝置設為靜音

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

action.devices.commands.setVolume

根據volumeMaxLevel設定音量大小。

參數

參數 類型 說明
volumeLevel 整數

必填。

新的音量,從 0volumeMaxLevel

範例

設定揚聲器裝置的絕對音量

{
  "command": "action.devices.commands.setVolume",
  "params": {
    "volumeLevel": 6
  }
}

action.devices.commands.volumeRelative

根據volumeMaxLevel設定,以 n 步調高或調低音量。使用相對體重的指令時,Google 助理會適當選取 n 來縮放至可用步驟。舉例來說,「提高電視的音量」可設定比「讓電視更加小聲」的步驟數較多。

參數

參數 類型 說明
relativeSteps 整數

必填。

代表「遞減」。

範例

在僅限指令模式下設定揚聲器裝置的相對音量

{
  "command": "action.devices.commands.volumeRelative",
  "params": {
    "relativeSteps": -1
  }
}

裝置錯誤:ERRORS

請參閱錯誤和例外狀況的完整清單。
  • volumeAlreadyMax:裝置在最大音量時會收到 VolumeUp 指令。
  • volumeAlreadyMin:如果裝置已處於最小音量,則會收到 VolumeDown 指令。