處理錯誤和例外狀況

如果裝置或要求無法正常運作,請務必為使用者提供良好的錯誤處理和通訊機制,讓他們瞭解發生了什麼事,並盡可能瞭解如何修正問題。請務必仔細思考可能發生的失敗情況,以及裝置應如何回應:如果使用者中斷進行中的工作會怎麼樣?如果使用者在裝置離線時要求執行動作,該如何處理?規劃如何解決這些問題,並協助使用者從中復原,可避免使用者感到沮喪,並為裝置打造更高品質的體驗。

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

範例 1:EXECUTE 意圖的錯誤回應

使用者在客廳安裝了兩盞智慧型燈具。使用者發出「打開客廳的燈」指令,Google 將 EXECUTE 意圖傳送至你的完成網址。你發現使用者的裝置處於離線狀態,無法控制,因此履約作業會傳回 EXECUTE 回應,其中包含 status ERRORerrorCode deviceOffline

這個範例說明如何從燈具裝置傳回含有 errorCodeEXECUTE 回應,如先前所述:

{
  "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 SUCCESSexceptionCode lowBattery

這個範例說明如何從門鎖裝置傳送含有 exceptionCodeEXECUTE 回應,如先前所述:

{
  "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,請參閱「錯誤和例外狀況」參考說明文件。