错误和异常

本文档列出了智能家居设备正式支持的错误和异常。请在 intent 响应中或通知（如果实现了该功能）中使用这些给定的错误和异常代码，以便 Google 助理提醒最终用户注意与给定命令或设备状态相关的问题。如果响应包含不正确的格式或 errorCode，Google 助理会为用户提供一条通用错误消息，例如“抱歉，设备目前无法使用”。

错误

当某个问题导致执行或查询请求失败时，您应该返回错误代码。例如，如果门锁卡住而无法锁定或解锁，则应向用户返回关于此状态的错误。

错误代码可在设备级别或全局级别添加。例如，如果用户有许多来自一个提供方的灯，并且它们由 hub 控制，则当用户要求关闭所有灯时，提供程序可以在单个灯处于离线状态时返回设备级错误，或者在整个 hub 处于离线状态并且无法控制任何灯时返回全局级错误。如果所有设备都处于离线状态，则使用全局级错误或设备级错误没有任何区别。当设备离线时，您应返回 reportState 中的 {"online": false} 状态，即使返回 deviceOffline 错误代码也是如此。

总结：

• 全局级错误：响应中的所有设备都有相同的错误
• 本地级错误：混合响应与错误和成功案例

全局级错误

以下 JSON 代码段展示了如何在 QUERY 或 EXECUTE 响应中返回全局级错误。

由于 hub 处于离线状态，因此出现全局级错误 deviceOffline：

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

由于 hub 更新而产生的全局级错误 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。

{
  "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"
      }
    }]
  }
}

{
  "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"
        }]
      }
    }]
  }
}

{
  "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"
          }
        ]
      }
    }
  }
}