錯誤和例外狀況

本文件列出智慧型家居裝置的官方支援錯誤和例外狀況。請在意圖回應中使用這些指定的錯誤和例外狀況代碼，或在通知中使用 (如果您已實作)，以便 Google 助理向使用者發出警報，告知與特定指令或裝置狀態相關的問題。如果回應包含錯誤的格式或 errorCode，Google 助理會向使用者顯示一般錯誤訊息，例如「很抱歉，裝置目前無法使用」。

錯誤

當問題導致執行或查詢要求失敗時，您應傳回錯誤代碼。舉例來說，如果門鎖卡住，無法上鎖或解鎖，應向使用者傳回有關此狀態的錯誤。

錯誤代碼可附加至裝置層級或全域層級。舉例來說，如果使用者擁有多盞由單一供應商提供的燈具，且這些燈具由中樞控制，當使用者要求關閉所有燈具時，如果單一燈具離線，供應商可能會傳回裝置層級錯誤；如果整個中樞離線，且無法控制任何燈具，供應商可能會傳回全域層級錯誤。如果所有裝置都處於離線狀態，使用全域層級或裝置層級錯誤並無差異。

裝置離線時，您應在裝置行為發生後的 5 分鐘內，將 {"online": false} 回報至 Report State。

摘要說明：

• 全域層級錯誤：回應中的所有裝置都發生相同錯誤
• 區域層級錯誤：回應內容混雜，包含錯誤和成功案例

全域層級錯誤

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

裝置層級錯誤

查詢回應

下列 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。

例外狀況

如果指令發生問題或顯示快訊，您應傳回例外狀況。指令可能會成功或失敗。

如果指令成功 (狀態 =「SUCCESS」)，請使用 StatusReport 特徵 (針對目標以外的裝置) 或傳回適當的 exceptionCode (針對目標裝置)，回報例外狀況。

舉例來說，如果烘衣機的棉絮濾網已滿，使用者仍可啟動烘衣機，但您可能會針對這種狀態發出警告。同樣地，當裝置電量不足但未完全耗盡時，您仍可執行指令，但應讓他們知道裝置電量不足。

如果指令因例外狀況而失敗，狀態應為「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。