處理錯誤和例外狀況

當裝置或要求無法正常運作時,請務必為使用者提供良好的錯誤處理機制和通訊內容,讓使用者瞭解發生的事件,並盡可能瞭解修正方法。請務必審視可能發生的失敗情況,以及裝置會如何回應:如果使用者中斷執行中的工作,該怎麼辦?如果使用者在離線時透過裝置要求動作,該怎麼做?為解決這些問題並協助使用者進行復原,就能避免造成使用者困擾,並打造更優質的裝置體驗。

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

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

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

這個範例說明如何透過淺色裝置傳回 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 SUCCESSexceptionCode lowBatteryEXECUTE 回應。

以下範例說明如何從鎖定裝置傳送包含 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:後續通知

針對支援後續追蹤通知的 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,請參閱錯誤和例外狀況參考說明文件。