當裝置或要求無法正常運作時,請務必為使用者提供良好的錯誤處理機制和通訊內容,讓使用者瞭解發生的事件,並盡可能瞭解修正方法。請務必審視可能發生的失敗情況,以及裝置會如何回應:如果使用者中斷執行中的工作,該怎麼辦?如果使用者在離線時透過裝置要求動作,該怎麼做?為解決這些問題並協助使用者進行復原,就能避免造成使用者困擾,並打造更優質的裝置體驗。
本指南提供了一些用於處理錯誤的意圖回應範例。請參閱錯誤和例外狀況,瞭解有效的 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
回應。
以下範例說明如何從鎖定裝置傳送包含 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:後續通知
針對支援後續追蹤通知的 traits 指令,您可以在發生錯誤或出現例外狀況時傳送後續通知給使用者 (如果已實作 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
,請參閱錯誤和例外狀況參考說明文件。