如果裝置或要求無法正常運作,請務必為使用者提供良好的錯誤處理和通訊機制,讓他們瞭解發生了什麼事,並盡可能瞭解如何修正問題。請務必仔細思考可能發生的失敗情況,以及裝置應如何回應:如果使用者中斷進行中的工作會怎麼樣?如果使用者在裝置離線時要求執行動作,該如何處理?規劃如何解決這些問題,並協助使用者從中復原,可避免使用者感到沮喪,並為裝置打造更高品質的體驗。
本指南提供一些處理錯誤的意圖回應範例。請參閱「錯誤和例外狀況」,瞭解錯誤和例外狀況的有效 errorCode
值。
範例 1:EXECUTE
意圖的錯誤回應
使用者在客廳安裝了兩盞智慧型燈具。使用者發出「打開客廳的燈」指令,Google 將 EXECUTE
意圖傳送至你的完成網址。你發現使用者的裝置處於離線狀態,無法控制,因此履約作業會傳回 EXECUTE
回應,其中包含 status
ERROR
和 errorCode
deviceOffline
。
這個範例說明如何從燈具裝置傳回含有 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
意圖的非封鎖例外狀況
使用者嘗試透過 Assistant 鎖上大門的智慧門鎖。你可以順利控制門鎖,但發現裝置電量不足,因此完成要求時會傳回 EXECUTE
回應,並包含 status
SUCCESS
和 exceptionCode
lowBattery
。
這個範例說明如何從門鎖裝置傳送含有 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
,請參閱「錯誤和例外狀況」參考說明文件。