欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。

处理错误和异常

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

当设备或请求未按预期方式工作时,请务必向用户提供良好的错误处理和通信机制,以便他们了解发生的情况,并尽可能了解如何纠正。请务必仔细考虑可能出现的故障场景和设备响应方式:如果用户中断正在进行中的任务,会发生什么情况?如果用户在离线状态下请求设备执行操作,会怎么样?针对这些问题做好规划并帮助用户从这些问题中恢复过来,可以避免用户感到沮丧并为您的设备打造更优质的体验。

本指南提供了一些用于处理错误的 intent 响应示例。如需查看错误和异常的有效 errorCode 值,请参阅错误和异常参考文档

示例 1:针对 EXECUTE intent 的错误响应

最终用户在客厅安装了两个智能灯。用户发出“打开客厅的灯”的指令,Google 向你的执行方式网址发送 EXECUTE intent。你发现用户的设备处于离线状态且不受控制,因此你的执行方式会返回包含 status ERRORerrorCode deviceOfflineEXECUTE 响应。

下文示例演示了如何从灯设备返回带有 errorCodeEXECUTE 响应(如前所述):

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

Google 助理在收到响应后会提示用户“该设备目前不可用”。请注意,在 EXECUTE 响应中发送 errorCode deviceOffline 后,仍需为处于报告状态的设备发送离线状态。

示例 2:针对 EXECUTE intent 的非阻塞异常

一位用户尝试使用内置 Google 助理的设备锁上前门的智能锁。您可以成功控制用户的锁,但发现设备的电池电量不足,因此您的执行方式会返回包含 status SUCCESSexceptionCode lowBatteryEXECUTE 响应。

此示例演示了如何从锁定设备发送包含 exceptionCodeEXECUTE 响应(如前所述):

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

收到响应后,Google 助理会提示用户“设备电量不足”。

示例 3:主动式错误通知

在某些情况下,在出现错误时提醒用户是有益的做法,尤其是对于用户认为会自动完成的功能。对于支持主动通知的特征,如果你已实现智能家居主动通知功能,则可以在出现错误时主动通知用户。

一台智能烘干机正在运行,有人在烘干程序结束之前打开了门。你可以调用 Home Graph API reportStateAndNotifications 方法来发送包含 errorCode 的主动通知:

此示例演示了如何从烘干机设备发送包含 errorCode 的主动通知(如前所述):

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

Google 助理在收到通知后,会提示用户“设备门已打开”。您可以在同一载荷中随通知一起发送相应的设备状态和通知。

示例 4:跟进通知

对于支持后续通知的特征命令,如果你已实现智能家居跟进通知,则可以在出现错误或异常时向用户发送后续通知。

用户发出关闭车库门的指令,但门在关闭时卡住了。你可以发送包含 errorCode 的跟进通知:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

Google 助理在收到通知后,会提示用户“设备卡住了”。相应的设备状态可以和通知一起在同一载荷中发送。

如需了解详情和详细的 errorCodes,请参阅错误和异常参考文档。