如果裝置或要求無法正常運作，請務必為使用者提供良好的錯誤處理和通訊機制，讓他們瞭解發生了什麼事，並在可行情況下說明如何修正。請務必考慮可能的失敗情境，以及裝置應如何回應：如果使用者中斷進行中的任務，該怎麼辦？如果使用者在裝置離線時要求執行動作，該怎麼辦？預先規劃這些問題，並協助使用者復原，可避免使用者感到挫折，並為裝置打造更優質的體驗。
本指南提供一些處理錯誤的意圖回應範例。請參閱「錯誤和例外狀況」，查看錯誤和例外狀況的有效 errorCode 值。
示例 1：EXECUTE 意圖的錯誤回應
使用者在客廳安裝了兩盞智慧型燈具。使用者下達「打開客廳燈」指令，Google 會將 EXECUTE 意圖傳送至你的執行網址。您發現使用者的裝置處於離線狀態且無法控制，因此執行階段會傳回含有 status ERROR 和 errorCode deviceOffline 的 EXECUTE 回應。
以下範例說明如何從燈具裝置傳回 EXECUTE 回應，並附上 errorCode，如前文所述：
{
"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 意圖的非阻斷例外狀況
使用者嘗試使用 Assistant 鎖上前門的智慧型門鎖。您可以成功控制鎖，但發現裝置電池電量不足，因此服務供應商會傳回含有 status SUCCESS 和 exceptionCode lowBattery 的 EXECUTE 回應。
以下範例說明如何透過鎖定裝置傳送 EXECUTE 回應，並附上 exceptionCode，如前文所述：
{
"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 的詳細資訊，請參閱「錯誤和例外狀況」參考說明文件。