歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。

錯誤和例外狀況

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本文件列出了智慧住宅裝置的官方支援錯誤和例外狀況。請在意圖回應中使用這些指定錯誤和例外狀況代碼;如果您導入了通知,即可使用這些錯誤,因此 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"
      }
    }
  }
}

EXECUTE 回覆

下列 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"
            }
          }
        }
      }
    }
  }
}

錯誤清單

下列錯誤將在裝置上產生相關的 TTS。

  • AboveMaximumLightEffectsDuration 超過了 1 小時的上限。請再試一次。
  • AbovemaxTimerDuration 我只能將 <device(s)> 設定 <time period>
  • actionNotAvailable 很抱歉,我目前無法執行這項操作。
  • ActionUnavailableWhenRunning <device(s)> <is/are> 正在運行,因此我不能做任何更改。
  • Armed: <device(s)> <is/are> is armd.
  • AtAtMax <device(s)> <is/are> 已設為最高溫度。
  • AtAtMin <device(s)> <is/are> 已設為最低溫度。
  • 已結案 <device(s)> <is/are> 已停業。
  • 現有 Disarmed <device(s)> <is/are>已經解除了。
  • 已插入 <device(s)> <is/are> 已停靠。
  • InInState <device(s)> <is/are> in the state.
  • locklocked <device(s)> <is/are> 已鎖定。
  • OffOff <device(s)> <is/are> 已關閉。
  • OnOn <device(s)> <is/are> 已開啟。
  • 已開放 <device(s)> <is/are> 已經開啟。
  • 已暫停 <device(s)> <is/are> 已暫停。
  • 已啟動 <device(s)> <is/are> 已開始。
  • StopStopped <device(s)> <is/are>已停止。
  • 已解鎖 <device(s)> <is/are> 已解鎖。
  • ambiguousZoneName很抱歉,<device(s)> 無法辨識你指定的區域。請確認各個區域皆有專屬名稱,然後再試一次。
  • amountAboveLimit 這不只是 <device(s)> 所能支援的。
  • appLaunchFailed很抱歉,無法在 <device(s)> 上啟動 <app name>。
  • armFailure <device(s)> 無法啟動。
  • armLevel Needed 我不確定要將 <device(s)> 設定為哪個層級。請試著說出「將 <裝置> 設為 [低安全性]」或「將 <裝置> 設為 <安全性>」。
  • authFailure 我無法連上 <裝置>。請嘗試檢查應用程式,確認<裝置/裝置> <is/are>已完全完成設定。
  • FullFull <device(s)> <has/have> <a pack 袋/滿袋 > 。請清空 <it/them>,然後再試一次。
  • 低於 LightLightEffectsDuration 這個時間不到 5 分鐘的最短持續時間。請再試一次。
  • UnderMinimumTimerDuration 我無法為 <device(s)> 設定這麼短的時間。請再試一次。
  • binFull<device(s)> <has/have> <a bin/full bins>。
  • cancelArmingRestricted抱歉,我無法取消啟動 <device(s)>。
  • cancelTooLate很抱歉,現在取消的期限已過。請改用 <device(s)> 或應用程式。
  • channelSwitchFailed很抱歉,無法切換至「<channel name>」頻道,請稍後再試。
  • 充電器問題很抱歉,系統似乎顯示 <device(s)> <has/have> <a 充電器問題/充電器問題>。
  • commandInsertFailed無法處理 <device(s)> 的指令。
  • deadBattery <device(s)> <has/have> <a 電池電力/續航力電池>
  • degreeOutOfRange 要求的度數超出 <device(s)> 的範圍。
  • deviceAlertneedsAssistance<device(s)> <has/have> 項未解決的快訊和 <need(s)> 您的協助。
  • deviceAtExtremeTemperature <is/are>> <is/are> 在 <a 極端溫度/極端溫度>
  • deviceBusy 很抱歉,<device(s)> 目前正在執行任何動作。
  • deviceCharging 很抱歉,<device(s)> 無法執行這項作業,因為 (ha_shared.Itsersre size=$item.devices.total_device_count) 正在充電。
  • deviceClogged 抱歉,<device(s)> 似乎卡住了。
  • deviceCurrentlyDispensing<device(s)> 目前正在供應東西。
  • deviceDoorOpen <device(s)> 的車門是開著的,請關閉車門,然後再試一次。
  • DeviceHandleClosed <device(s)> 的控點已經關閉。請開啟手柄,然後再試一次。
  • deviceJammingDetected <device(s)> <is/are> 卡住了。
  • deviceLidOpen<device(s)> 的蓋子已打開。請關閉開關,然後再試一次。
  • device NeedsRepair <device(s)> <needss> 待維修。請與您的當地服務經銷商聯絡。
  • deviceNotDocked很抱歉,<device(s)> <isn't/aren't> 沒有座架。請將 <it/them> 插入座架,然後再試一次。
  • deviceNotFound <device(s)> <is/are> 無法使用。建議你重新設定 <it/them>。
  • deviceNotmounted很抱歉,<device(s)> 無法安裝,因為 <it/他們> <尚未安裝
  • deviceNotReady <device(s)> <is/are>尚未準備好。
  • deviceStuck <device(s)> <is/are> 停滯不前,需要協助。
  • deviceTampered <device(s)> <has/have> 遭到竄改。
  • deviceThermalShutdown 很抱歉,<device(s)> 似乎因極端溫度而關閉。
  • directResponseOnlyUnreachable<device(s)> <不/不支援> 支援遙控功能。
  • disarmFailure <device(s)> 無法解除。
  • dreteOnlyOpenClose 很抱歉,<device(s)> 只能完全開啟或關閉。
  • DispenseAmountAboveLimit <device(s)> 無法供應這麼多的金額。
  • DispenseAmountBelowLimit <device(s)> 無法供應這麼少的小額費用。
  • DispenseAmountRemainingExceeded <device(s)> 的 <dispense item> 數量不足,無法執行這項動作。
  • DispenseFractionalAmountNotSupported <device(s)> 無法供應 <dispense item> 的分數。
  • dispenseFractionalUnitNotSupported <device(s)> 不支援針對 <dispense item> 的單位使用分數值。
  • dispenseUnitNotSupported <device(s)> 不支援針對 <dispense item> 的單位。
  • ClosedClosedTooLong <device(s)> 的車門打開了一段時間,請打開門確定一下裡面有放東西,然後再試一次。
  • 緊急服務啟動 在裝置處於緊急熱源模式下 <裝置/> <is/are>,因此 <it/他們> 必須手動調整。
  • faultyBattery <device(s)> <has/have> <a 有不良的電池/電池故障>。
  • floorUnreachable<device(s)> 無法到達該房間。請將 <it/them> 移至正確的樓層,然後再試一次。
  • FunctionNotSupported 事實上,<device(s)> <不/不> 支援該功能。
  • genericDispenseNotSupported 我想知道您想要供應什麼。請使用項目的名稱再試一次。
  • HarError 抱歉,系統發生錯誤,無法控制你的家用裝置。
  • HarError 抱歉,系統發生錯誤,無法控制你的家用裝置。
  • 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 <裝置> 目前<br/>正在軟體更新中。
  • lockFailure:無法鎖定 <device(s)>
  • lockState:目前<device(s)> <is/are> 處於鎖定狀態。
  • lockToRange : 這個溫度不在 <device(s)> 的鎖定範圍內。
  • lowBattery <device(s)> <has/have> 電量不足。
  • maxSettingReached <device(s)> <is/are> 已設為最高的設定。
  • maxSpeedReached<device(s)> <is/are> 已設為最高速度。
  • minSettingReached <device(s)> <is/are> 已設為最低設定。
  • minSpeedReached <device(s)> <is/are> 已設為最低速度。
  • monitoringServiceConnection Loss <device(s)> <has/have> 與監控服務的 <its/the> 連線中斷。
  • needAttachment 很抱歉,<device(s)> <is/are> 缺少必要的附件。請安裝後再試一次
  • needBin 很抱歉,<device(s)> <is/are> 缺少集塵盒。請安裝後再試一次
  • needPads <device(s)> <need(s)> 個新墊片。
  • needSoftwareUpdate<device(s)> <need(s)> 軟體更新。
  • needWater <device(s)> <need(s)> 水。
  • networkProfileNotRecognized很抱歉,我無法辨識 <device(s)> 上的「<network 設定檔>」。
  • networkSpeedTestInProgress我已測試 <network> <speed/speeds>>。
  • noAvailableApp很抱歉,<app name> 無法使用。
  • noAvailableChannel很抱歉,目前沒有「<channel name>」這個頻道。
  • noChannelSubscription很抱歉,您目前並未訂閱「<channel name>」頻道。
  • noTimerExists 很抱歉,<device(s)> 上沒有設定任何計時器。
  • 不支援很抱歉,<device(s)> 不支援這個模式。
  • obstructionDetected <device(s)> 偵測到障礙物。
  • 離線 、裝置離線 很抱歉,<device(s)> 目前<無法使用>
  • onOnsMode:請指定要啟用的模式。
  • 通關密語錯誤 很抱歉,這組 PIN 碼似乎不正確。
  • percentOutOfRange很抱歉,我無法將 <device(s)> 設為 <percent>。
  • pinIncorrect(passphraseIncorrect)
  • rainDetected 由於偵測到雨水,我未開啟 <裝置(>)
  • rangeTooClose 如果 <device(s)> 的熱 • 冷範圍太小,則兩者太接近。請選擇溫度範圍較遠的溫度。
  • 必要連結 很抱歉,你的帳戶似乎出現錯誤。請透過「Google Home」或「Google 助理」應用程式重新連結 <裝置>。
  • remoteSetDisabled
    • 選用參數 errorCodeReason
    • currentlyArmed - 很抱歉,由於安全性已經啟動,你必須使用 <device(s)> 或應用程式才能變更設定。
    • remoteUnlockNotAllowed - 很抱歉,我無法從遠端解鎖 <device(s)>。
    • remoteControlOff - 這個動作目前已停用。請啟用 <device(s)> 的遙控器,然後再試一次。
    • childSafetyModeActive - 在兒童安全模式啟用時,系統會為 <device(s)> 停用這個動作。
  • roomOn 分隔樓層 <device(s)> 位於那些樓層,因此無法進入這些房間。
  • safetyShutOff<device(s)> <is/are> 在安全關機模式中,因此 <it/他們> 必須手動調整。
  • scapeCannotBeApplied 很抱歉,無法套用 <device(s)>。
  • securityRestriction<device(s)> <has/have> 受到安全性限制。
  • softwareUpdateNotAvailable很抱歉,<device(s)> 沒有可用的軟體更新。
  • startstartsTime
  • tillCoolingDown <device(s)> <is/are> 仍然在降溫。
  • tillWarmingUp <device(s)> <is/are> 仍然正在暖身。
  • streamUnavailable 抱歉,這個串流目前不適用於 <device(s)>。
  • streamUnplayable很抱歉,我目前無法播放 <device(s)> 的串流內容。
  • tankEmpty<device(s)> <has/have> <一個空的坦克/空坦克>。請填寫 <it/them>,然後再試一次。
  • target targetreached很抱歉,這已經是目前溫度。
  • rtimeValueOutOfRange<device(s)> 無法在指定時間內進行設定。
  • Many ManyFailedults 很抱歉,失敗次數過多,請前往裝置的應用程式完成這項操作。
  • transientError 抱歉,控制 <device(s)> 時發生錯誤。請再試一次。
  • 關閉 , deviceOffedOff <device(s)> <is/are> 目前已關閉。
  • toToLocateDevice我找不到 <device(s)>。
  • UnknownFoodPreset <device(s)> 不支援這個食物預設設定。
  • 解鎖 Failure <device(s)> 無法解鎖。
  • unpausableState <device(s)> 目前無法暫停。
  • userCancelled確定
  • valueOutOfRange <device(s)> 無法設為這個溫度。

例外狀況

指令或問題發生關聯時應傳回例外狀況。指令可能會成功或失敗。

如果指令成功 (status = "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"
          }
        ]
      }
    }
  }
}

例外清單

以下例外狀況將在裝置上產生相關聯的 TTS。

  • FullFull <device(s)> <has/have> <a pack 袋/滿袋 > 。請清空 <it/them>,然後再試一次。
  • binFull<device(s)> <has/have> <a bin/full bins>。
  • 碳一氧化碳偵測 在 <房屋名稱> 中偵測到一氧化碳。
  • deviceAtExtremeTemperature <is/are>> <is/are> 在 <a 極端溫度/極端溫度>
  • 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> 未插電。
  • floorUnreachable<device(s)> 無法到達該房間。請將 <it/them> 移至正確的樓層,然後再試一次。
  • hardwareFailure<device(s)> <has/have> 硬體問題。
  • inSoftwareUpdate <裝置> 目前<br/>正在軟體更新中。
  • isBypassed:目前略過 <device(s)> <is/are>
  • lowBattery <device(s)> <has/have> 電量不足。
  • MotionDetected <device(s)> <detect(s)> 動作。
  • needPads <device(s)> <need(s)> 個新墊片。
  • needSoftwareUpdate<device(s)> <need(s)> 軟體更新。
  • needWater <device(s)> <need(s)> 水。
  • networkJammingDetected <device(s)> 的家用網路連線出現異常。
  • noIssuesReported<device(s)> 未回報任何問題。
  • roomOn 分隔樓層 <device(s)> 位於那些樓層,因此無法進入這些房間。
  • runCycleFinished<device(s)> <has/have> 已執行完畢。
  • securityRestriction<device(s)> <has/have> 受到安全性限制。
  • smokeDetected 在 <house name> 中偵測到煙霧。
  • tankEmpty<device(s)> <has/have> <一個空的坦克/空坦克>。請填寫 <it/them>,然後再試一次。
  • 使用 CellularBackup <is(are)> <is/are>使用行動網路備份。
  • waterLeakDetected <device(s)> <detect(s)> 漏水情形。