這份文件會列出官方支援的智慧住宅裝置錯誤和例外狀況。請使用意圖回應中的這些指定錯誤和例外狀況代碼;如果您實作過這些通知,請在通知中使用 Google 助理,提醒使用者與特定指令或裝置狀態相關的問題。如果回應的格式不正確或 errorCode
,Google 助理會為使用者提供一般錯誤訊息,例如「很抱歉,裝置目前不適用」。
錯誤
如果問題導致執行作業或查詢要求失敗,則應傳回錯誤代碼。例如,如果門鎖變成卡住且無法上鎖或解鎖,則應傳回這個狀態的相關錯誤。
錯誤代碼可附加至裝置層級或全域層級。舉例來說,如果使用者有一個來自特定供應商的燈,並由中樞控制,那麼當使用者要求關閉所有燈具時,供應商可能會傳回裝置層級錯誤;如果單一燈具處於離線狀態,且無法控制任何燈號,供應器就會傳回全域層級錯誤。如果所有裝置都處於離線狀態,則使用全域層級或裝置層級錯誤沒有差異。裝置處於離線狀態時,即使您傳回 deviceOffline
錯誤代碼,也應回報 reportState 中的 {"online": false}
狀態。
摘要說明:
- 全域層級錯誤:回應中的所有裝置都發生相同的錯誤
- 本地層級錯誤:混合錯誤、錯誤及成功案例
全域層級錯誤
下列 JSON 程式碼片段說明如何在 QUERY 或 EXECUTE 回應中傳回全域層級錯誤。
由於中樞導致的全域層級錯誤 deviceOffline
處於離線狀態:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
更新中樞的全域層級錯誤 inSoftwareUpdate
範例:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
裝置層級錯誤
「QUERY」回應
下列 JSON 程式碼片段說明如何在 QUERY 回應中傳回裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "errorCode": "deviceOffline", "status" : "ERROR" }, "device-id-2": { "errorCode": "deviceOffline", "status" : "ERROR" } } } }
執行回應
下列 JSON 程式碼片段顯示如何在 EXECUTE 回應中傳回裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "device-id-2" ], "status": "SUCCESS", "states": { "on": true, "online": true } } ] } }
含有錯誤的通知
主動通知
下列 JSON 程式碼片段說明如何在主動通知中回報裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } } } } }
後續追蹤回覆
下列 JSON 程式碼片段說明如何在後續回應中回報裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "PLACEHOLDER" } } } } } } }
錯誤清單
下列錯誤將在裝置上產生相關聯的文字轉語音。
- aboveMaxLightsDuration : 超過 1 小時的持續時間。請再試一次。
- aboveMaximumTimerDuration : 我最多只能將 <device(s)> 設為 <時間範圍>
- actionNotAvailable 很抱歉,我目前無法執行這個動作。
- actionUnavailableBetweenRunning : <device(s)> <is/are> 正在執行,因此我無法進行任何變更。
- 已將 Armed : <device(s)> <is/are> 已經啟動。
- AtAtMax : <device(s)> <is/are> 已設在最高溫度。
- hasAtMin : <device(s)> <is/are> 已設在最低溫度。
- ClosedClosed : <device(s)> <is/are> 已關閉。
- hasDisarmed : <device(s)> <is/are> 已解除。
- ockDocked : <device(s)> <is/are> 已插入座架。
- existingInState :<device(s)> <is/are> 處於該狀態。
- 已鎖定 : <device(s)> <is/are> 已鎖定。
- nowOff : <device(s)> <is/are> 已關閉。
- OnOn : <device(s)> <is/are> 已經啟用。
- openOpen : <device(s)> <is/are>已開啟。
- 已暫停 : <device(s)> <is/are> 已暫停。
- 開始時間: <device(s)> <is/are>已經開始。
- hasStopped : <device(s)> <is/are> 已停止。
- 已解鎖 : <device(s)> <is/are> 已解鎖。
- ambiguousZoneName : 很抱歉,<device(s)> 無法識別您要識別的區域。請確認各個區域皆有專屬名稱,然後再試一次。
- amountAboveLimit : 這超過 <device(s)> 能支援的功能。
- appLaunchFailed : 很抱歉,無法在 <device(s)> 上啟動 <應用程式名稱>。
- armFailure : <device(s)> 無法啟動。
- armLevelNeeded : 我不確定要將 <device(s)> 設為哪個層級。請試著說出「將 <device(s)> 設為 <低安全性>」或「將 <裝置> 設為 <高安全性>」
- AuthAuth : 我找不到 <device(s)>。請檢查應用程式,確認 <裝置/裝置> <is/are> 設定完成。
- packFull : <device(s)> <has/have> <a full pack/fullss 巴 s"。請將 <it/them> 留空,然後再試一次。
- 低於 MinLightEffectsDuration : 小於 5 分鐘的長度下限。請再試一次。
- UnderMinrDuration : 我無法為這類短時間內設定 <device(s)>。請再試一次。
- binFull :<device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted : 很抱歉,我無法取消啟動 <device(s)>。
- cancelTooLate : 很抱歉,現在太晚了。請改用 <device(s)> 或應用程式。
- channelSwitchFailed : 很抱歉,無法切換至「<頻道名稱>」頻道,請稍後再試。
- IssueIssue : 抱歉,<device(s)> <has/have> <a 充電器問題/充電器問題>。
- commandInsertFailed : 無法處理 <device(s)> 的指令。
- deadBattery : <device(s)> <has/have> <a de Battery/dead batteries>.
- degreeOutOfRange : 要求溫度不在 <device(s)> 範圍內。
- 裝置 Alert 需要 協助 : <device(s)> <has/have> 開啟中的快訊,並提供協助 <need(s)>。
- deviceAtExtremeTemperature : <device(s)> <is/are> <a tremedegree/timeremedegrees>。
- deviceBusy : 很抱歉,<device(s)>目前似乎已在執行其他動作。
- deviceCharging : 抱歉,<device(s)> 似乎因為 (ha_shared.ItsAndre size=$item.devices.total_device_count) 充電,因此無法執行這個動作。
- deviceClogged : 抱歉,<device(s)> 似乎被駭。
- DeviceCurrentlyDispenss : <device(s)> 現已在消耗其他內容。
- deviceDoorOpen : 車門在 <device(s)> 上開幕。請關閉這個開關,然後再試一次。
- deviceHandleClosed : 帳號在 <device(s)> 上會關閉。請打開帳號代碼,然後再試一次。
- deviceJammingDetected : <device(s)> <is/are> 遭到破壞。
- deviceLidOpen : 機蓋上在 <device(s)> 上開著。請關上盒,然後再試一次。
- deviceNeedsRepair : <device(s)> <need(s)> 即可維修。請與您的當地經銷商聯絡。
- DeviceNotDocked : 抱歉,<device(s)> <isn't/aren't> 已停放在座架上。請先將 <it/them> 固定,然後再試一次。
- deviceNotFound : <device(s)> <is/are> 無法使用。建議你重新設定 <it/them>。
- DeviceNotMounted : 很抱歉,<device(s)> 似乎<it/are>無法掛載,因此無法執行這個動作。
- deviceNotReady : <device(s)> <is/are>尚未準備就緒。
- deviceStuck : <device(s)> <is/are> 停滯,需要你的協助。
- deviceTampered : <device(s)> <has/have>遭到竄改。
- deviceThermalShutdown :抱歉,<device(s)>似乎因為極端溫度而關機。
- directResponseOnlyUnreachable : <device(s)> <doesn't/don'> support 遙控器。
- aarmFailure : <device(s)> 無法解除。
- DisreteOnlyOpenClose : 很抱歉,<device(s)> 只能完全開啟或關閉。
- DispenseAmountAboveLimit : <device(s)> 無法處理這麼龐大的費用。
- DispenseAmountBelowLimit : <device(s)> 無法負責處理這類小額費用。
- dispenseAmountRemainingExceeded : <device(s)> <ppense item> 不足,因此無法執行這項作業。
- dispenseFracativeAmountNotSupported : <device(s)> 無法分配部分 <dispense 項目>。
- dispenseFracativeUnitNotSupported : <device(s)> 不支援該單位的 <dispense 項目。
- dispenseUnitNotSupported : <device(s)> 不支援這個<dispense 項目>的單位。
- doorClosedTooLong : 從 <device(s)> 門打開了一段時間,請打開門確定一下裡面有放東西,然後再試一次
- EmergencyHeatOn : <device(s)> <is/are> 處於緊急熱源模式,因此 <it/他們的>必須手動調整。
- 電池故障 : <裝置(s)> <has/have> <a 電池錯誤/電池電池>。
- floorfloorable : <device(s)> 無法到達該房間。請將 <it/them> 移到正確的樓層,然後再試一次。
- FunctionNotSupported : <device(s)> <不/建議> 支援這項功能。
- genericDispenseNotSupported : 我想知道需要深入瞭解的內容,請使用項目名稱再試一次。
- hardError : 很抱歉,出了點小狀況,我無法控制你的住宅裝置。
- hardError : 很抱歉,出了點小狀況,我無法控制你的住宅裝置。
- inAutoMode : <device(s)> <is/are>目前設為自動模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inAwayMode : <device(s)> <is/are>目前設為外出模式。如要控制溫度控制器,請使用手機、平板電腦或電腦上的「Nest」應用程式,手動將溫度控制器切換成在家模式。
- inDryMode : <device(s)> <is/are> 目前設為模擬模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inEcoMode : <device(s)> <is/are> 目前已設為節能模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inFanOnlyMode : <device(s)> <is/are> 目前已設為送風模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inHeatOrCool : <device(s)> <is/are> 尚未處於熱 • 冷模式。
- inHumidifierMode : <device(s)> <is/are> 目前設為加濕器模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inOffMode : <device(s)> <is/are> 已關閉。如要變更溫度,請將 <it/them> 切換至其他模式。
- inPurifierMode : <device(s)> <is/are> 目前設為淨化模式。如要調整溫度,請將 <it/them> 切換為其他模式。
- inSleepMode : <device(s)> <is/are> 睡眠模式。請稍後再試。
- inSoftwareUpdate : <device(s)> <is/are> (軟體更新)。
- lockFailure : <device(s)> 無法鎖定。
- LockState : <device(s)> <is/are> 目前處於鎖定狀態。
- lockToRange : 這個溫度不在 <device(s)> 的鎖定範圍內。
- BatteryBattery : <device(s)> <has/have> 電力不足。
- maxSettingreached : <device(s)> <is/are> 已調到最高設定。
- maxSpeedReached : <device(s)> <is/are> 已設為最高速度。
- minSettingreached : <device(s)> <is/are> 已設為最低設定。
- minSpeedReached : <device(s)> <is/are> 已設為最低速度。
- monitoringServiceConnectionMissing : <device(s)> <has/have> 中斷 <its/its> 與監控服務的連線。
- needAttachment : 很抱歉,<device(s)> <is/are> 缺少必要的附件。請裝上後再試一次。
- needBin : 抱歉,<device(s)> <is/are> 似乎沒有集塵盒。請裝上後再試一次。
- 需求 Pads : <device(s)> <need(s)> 新墊。
- needSoftwareUpdate : <device(s)> <need(s)> 軟體更新。
- needWater : <device(s)> <need(s)> 水。
- networkProfileNotRecognized : 很抱歉,我無法辨識 <device(s)> 上的 <網路設定檔>。
- networkSpeedTestInProgress : 我已測試<網路>的<速度/速度>>。
- noAvailableApp : 很抱歉,<應用程式名稱> 似乎無法使用。
- noAvailableChannel : 很抱歉,「<頻道名稱>」似乎無法使用。
- noChannelSubscription : 很抱歉,你目前並未訂閱「<channel name>」頻道。
- noTimerExists : 很抱歉,<device(s)> 上沒有設定任何計時器。
- notSupported : 很抱歉,<device(s)> 無法使用這個模式。
- obstructionDetected : <device(s)> 偵測到障礙物。
- 離線 裝置 離線 : 很抱歉,<device(s)> 目前似乎<is/are>無法使用。
- onRequiresMode : 請指定要開啟的模式。
- 通關密語有誤 : 抱歉,PIN 碼似乎不正確。
- percentOutOfRange : 很抱歉,我無法將 <device(s)> 設為 <percent>。
- pinIncorrect : (passphraseIncorrect)
- rainDetected : 由於你偵測到雨水,我並未開啟 <device(s)>。
- rangeTooClose : 在 <裝置> 的熱 • 冷範圍太近,請選擇溫度範圍較廣的溫度。
- relinkRequired : 抱歉,您的帳戶出現錯誤。請透過 Google Home 或 Google 助理應用程式重新連結 <裝置>。
-
remoteSetDisabled
:
- 自選參數
errorCodeReason
currentlyArmed
- 抱歉,保全系統已啟動,你必須透過 <device(s)> 或應用程式才能變更設定。remoteUnlockNotAllowed
- 抱歉,我無法從遠端解鎖 <device(s)>。remoteControlOff
- 目前已停用這個動作。請在 <device(s)> 上啟用遙控器,然後再試一次。childSafetyModeActive
- 在兒童安全模式已啟用時,系統會停用 <device(s)> 的操作。
- 自選參數
- roomOnDifferenceFloors : <device(s)> 無法移動到那些房間,因為那些房間位於其他樓層。
- SafetyShutOff : <device(s)> <is/are>在安全關機模式下運作,因此<it/他們的>必須手動調整。
- 或使用 CannotBeApply : 很抱歉,<device(s)> 無法套用。
- SecurityRestriction : <device(s)> <has/have>安全性限制。
- SoftwareUpdateNotAvailable : 很抱歉,<device(s)> 沒有軟體更新。
- startRequiresTime : 如要這麼做,你必須告訴我要執行 <device(s)> 多久。
- tillCoolingDown :<device(s)> <is/are> 仍在降溫。
- WWmingmingUp : <device(s)> <is/are> 仍在暖機。
- streamUnavailable : 很抱歉,<device(s)> 目前似乎無法觀看直播。
- streamUnplayable : 很抱歉,我目前無法播放「<device(s)>」的串流內容。
- tankEmpty : <device(s)> <has/have> <an tank/empty tanks>。請填寫 <it/them>,然後再試一次。
- target alreadyreached : 抱歉,目前已經是目前的溫度。
- AMValueOutOfRange : <device(s)> 無法設定該時間長度。
- TooManyFaileds : 很抱歉,失敗的次數過多。請前往裝置上的應用程式完成這項操作。
- transientError : 很抱歉,控制 <device(s)> 時發生錯誤,請再試一次。
- OffOff , deviceTurnedOff : <device(s)> <is/are> 立即關閉。
- canToLocateDevice : 我找不到 <device(s)>。
- UnknownFoodPreset : <device(s)> 不支援這項食物預設設定。
- Unlockry : <device(s)> 無法解鎖。
- unpausableState : <device(s)> 目前無法暫停。
- userCancelled :確定
- valueOutOfRange : <device(s)> 無法設為這個溫度。
例外狀況
如果有與指令相關的問題或快訊,您應傳回例外狀況。指令執行成功或失敗。
如果指令成功 (狀態 =「SUCCESS」),請使用 StatusReport
特性 (針對目標以外的裝置) 回報例外狀況,或傳回適當的 exceptionCode
(為目標裝置)。
例如,如果乾燥的 Lint 畫面已滿,使用者仍可以啟動烘乾機,但您可能會想警告他們這個狀態。同理,如果裝置的電池電量偏低,且電力並未空白,您仍然可以執行指令,但應告知裝置裝置電量不足。
如果指令因例外狀況而失敗,狀態應顯示為「EXCEPTIONS」,而應使用 StatusReport
特性回報例外狀況。
目標裝置的非封鎖例外狀況 (SUCCESS)
以下範例是鎖門的例子:
前門的電量不足,正在鎖上前門。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
使用 StatusReport 的其他裝置封鎖封鎖功能 (SUCCESS)
本範例是針對保全系統操作:好的,啟動保全系統。車窗打開了
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [{ "blocking": false, "deviceTarget": "sensor_id1", "priority": 0, "statusCode": "deviceOpen" }] } }] } }
使用 StatusReport 封鎖其他裝置的例外狀況
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "on": true, "online": true, "status": "EXCEPTIONS", "currentStatusReport": [{ "blocking": true, "deviceTarget": "device-id-1", "priority": 0, "statusCode": "lowBattery" }, { "blocking": true, "deviceTarget": "front_window_id", "priority": 1, "statusCode": "deviceOpen" }, { "blocking": true, "deviceTarget": "back_window_id", "priority": 1, "statusCode": "deviceOpen" } ] } } } }
例外清單
以下例外狀況會導致裝置產生相關聯的文字轉語音。
- packFull : <device(s)> <has/have> <a full pack/fullss 巴 s"。請將 <it/them> 留空,然後再試一次。
- binFull :<device(s)> <has/have> <a full bin/full bins>。
- carbonMonoxideDetected : 在 <house name> 中偵測到一氧化碳。
- deviceAtExtremeTemperature : <device(s)> <is/are> <a tremedegree/timeremedegrees>。
- deviceJammingDetected : <device(s)> <is/are> 遭到破壞。
- deviceMoved : <device(s)> <was/were>已移動。
- deviceOpen <device(s)> <is/are> 開啟中。
- deviceTampered : <device(s)> <has/have>遭到竄改。
- deviceUnplugged : <device(s)> <is/are> 未插入。
- floorfloorable : <device(s)> 無法到達該房間。請將 <it/them> 移到正確的樓層,然後再試一次。
- HardwareFailure : <device(s)> <has/have> 硬體問題。
- inSoftwareUpdate : <device(s)> <is/are> (軟體更新)。
- isBypassed : <device(s)>目前<is/are>已被略過。
- BatteryBattery : <device(s)> <has/have> 電力不足。
- MotionDetected : <device(s)> <detect(s)> 動作。
- 需求 Pads : <device(s)> <need(s)> 新墊。
- needSoftwareUpdate : <device(s)> <need(s)> 軟體更新。
- needWater : <device(s)> <need(s)> 水。
- networkJammingDetected : 無法使用 <device(s)> 的家用網路連線,
- noIssuesReported : <device(s)> 未回報任何問題。
- roomOnDifferenceFloors : <device(s)> 無法移動到那些房間,因為那些房間位於其他樓層。
- runCycleFinished : <device(s)> <has/have>執行完畢。
- SecurityRestriction : <device(s)> <has/have>安全性限制。
- mmokeDetected 系統在 <house name> 中偵測到煙霧。
- tankEmpty : <device(s)> <has/have> <an tank/empty tanks>。請填寫 <it/them>,然後再試一次。
- 使用 CellcellBackup : <device(s)> <is/are> 使用行動備份功能。
- waterLeakDetected : <device(s)> <detect(s)> 漏水。