当设备或请求无法按预期方式工作时，请务必为用户提供良好的错误处理和通信机制，以便他们了解所发生的情况，并尽可能了解如何进行纠正。请务必仔细考虑可能出现的故障场景和设备响应方式：如果用户中断正在进行的任务，会发生什么情况？如果用户在离线的设备上请求执行某个 Action，会发生什么情况？通过为这些问题做好规划并帮助用户从这些问题中恢复过来，您可以避免用户感到沮丧并提供更优质的设备体验。
本指南提供了一些用于处理错误的 intent 响应示例。请参阅错误和异常，了解错误和异常的有效 errorCode 值。
示例 1：针对 EXECUTE intent 的错误响应
最终用户在客厅安装了两个智能灯。用户发出“打开客厅的灯”的指令，Google 向您的执行方式网址发送 EXECUTE intent。你发现用户的设备处于离线状态且不受控制，因此你的执行方式会返回包含 status ERROR 和 errorCode deviceOffline 的 EXECUTE 响应。
此示例演示了如何从灯设备返回包含 errorCode 的 EXECUTE 响应（如前所述）：
{
"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 Assistant 在收到响应后会提示用户“该设备目前不可用”。请注意，在 EXECUTE 响应中发送 errorCode deviceOffline 后，您仍然需要为处于报告状态的设备发送离线状态。
示例 2：针对 EXECUTE intent 的非阻塞异常
一位用户尝试使用带有 Assistant 的设备锁上前门的智能锁。您可以成功控制用户的门锁，但发现设备电池电量不足，因此您的执行方式会返回包含 status SUCCESS 和 exceptionCode lowBattery 的 EXECUTE 响应。
下面的示例演示了如何从锁设备发送包含 exceptionCode 的 EXECUTE 响应（如前所述）：
{
"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"
}
}]
}
}
Assistant 在收到响应后会提示用户“设备电量不足”。
示例 3：主动式错误通知
在某些情况下，在出现错误时提醒用户是有益的做法，尤其是对于用户认为会自动完成的功能。对于支持主动通知的特征，如果您实现了 smart home 主动通知，则可以在发生错误时主动通知用户。
一台智能烘干机正在运行，有人在烘干程序结束之前打开了门。您可以调用 Google 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
}
}
}
}
}
Assistant 会在收到通知后提示用户“设备门已打开”。相应的设备状态可以和通知一起在同一载荷中发送。
示例 4：跟进通知
对于支持跟进通知的特征命令，如果您已实现 smart home 跟进通知，则可以在出现错误或异常时向用户发送跟进通知。
用户发出关闭车库门的命令，但门在关闭时卡住了。你可以发送包含 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
}
}
}
}
}
Assistant 会在收到通知后提示用户“设备卡住了”。相应的设备状态可以和通知在同一载荷中发送。
如需了解详情和详细的 errorCodes，请参阅错误和异常参考文档。