處理錯誤和例外狀況

當裝置或要求未正常運作時,請務必為使用者提供適當的錯誤處理和通訊方式,協助他們瞭解發生的狀況,並視情況修正問題。請務必考量所有可能的失敗情境,以及裝置的回應方式:如果使用者中斷進行中的工作,會發生什麼事?如果使用者離線時透過裝置要求動作,該怎麼辦?規劃這些問題並協助使用者順利復原這些問題,可用於避免使用者感到困擾,並為裝置建立更優質的使用體驗。

本指南提供幾個處理錯誤的意圖回應範例。請參閱錯誤和例外狀況一文,瞭解有效的 errorCode 錯誤和例外狀況。

範例 1:EXECUTE 意圖錯誤回應

一位使用者在客廳安裝了兩盞智慧型燈具。使用者發出「開啟客廳燈具」的指令,而 Google 將 EXECUTE 意圖傳送至執行要求網址。您發現使用者的裝置處於離線狀態,且無法控制,因此您的執行要求會傳回含有 status ERRORerrorCode deviceOfflineEXECUTE 回應。

以下範例說明如何從淺色裝置使用 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 SUCCESSexceptionCode lowBatteryEXECUTE 回應。

以下範例說明如何從鎖定裝置,利用 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,請參閱錯誤和例外狀況參考說明文件。