當裝置或要求未正常運作時，請務必為使用者提供適當的錯誤處理和通訊方式，協助他們瞭解發生的狀況，並視情況修正問題。請務必考量所有可能的失敗情境，以及裝置的回應方式：如果使用者中斷進行中的工作，會發生什麼事？如果使用者離線時透過裝置要求動作，該怎麼辦？規劃這些問題並協助使用者順利復原這些問題，可用於避免使用者感到困擾，並為裝置建立更優質的使用體驗。
本指南提供幾個處理錯誤的意圖回應範例。請參閱錯誤和例外狀況一文，瞭解有效的 errorCode 錯誤和例外狀況。
範例 1：EXECUTE 意圖錯誤回應
一位使用者在客廳安裝了兩盞智慧型燈具。使用者發出「開啟客廳燈具」的指令，而 Google 將 EXECUTE 意圖傳送至執行要求網址。您發現使用者的裝置處於離線狀態，且無法控制，因此您的執行要求會傳回含有 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 意圖的非封鎖例外狀況
使用者嘗試使用 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，請參閱錯誤和例外狀況參考說明文件。