歡迎來到 Google Home 開發人員中心,你可以在這裡學習如何學習智慧型住宅動作。注意事項:您將在 Actions 主控台建構動作。

錯誤和例外狀況

這份文件會列出官方支援的智慧住宅裝置錯誤和例外狀況。請使用意圖回應中的這些指定錯誤和例外狀況代碼;如果您實作過這些通知,請在通知中使用 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)> 漏水