错误和异常

本文档列出了官方支持的智能 家居设备请在 intent 中使用指定的错误和异常代码 或在通知中 如果您已实现此功能，Google 助理就会提醒最终用户注意 或设备状态如果响应中包含不正确的格式或 errorCode，Google 助理会向用户显示一般错误消息，例如 “抱歉，device目前无法使用。”

错误

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

您可以在设备级别或全局级别添加错误代码。例如： 如果用户有多个来自一个提供商的灯具，并且这些灯具由 hub 控制，则 如果用户要求关闭所有灯，提供商可能会返回 如果单个灯具处于离线状态，则会发生设备级错误；如果单个灯具处于离线状态，则显示全局级错误 他们的整个集线器都处于离线状态，无法控制任何灯具。如果所有 设备已离线，使用全局级还是设备级没有区别 错误。当设备离线时，您应在以下位置报告 {"online": false} 状态： reportState，即使您返回了 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。

异常

当出现与以下项相关的问题或提醒时，您应返回异常 命令。命令可能会成功或失败。

如果命令成功（状态 = "SUCCESS"），报告异常 使用 StatusReport 特征（针对目标以外的其他设备）； 或返回适当的 exceptionCode（针对目标设备）。

例如，如果烘干机 lint 屏幕满了，用户仍可启动 但您可能需要警告他们有关此状态的信息。同样，如果 设备电量低但并非是空的，您仍然可以执行命令 但应让他们知道设备电量不足

如果命令因异常而失败，则状态应为“EXCEPTIONS” 异常应使用 StatusReport trait 报告。

与目标设备相关的非阻塞异常 (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。