處理錯誤和例外狀況

如果裝置或要求無法正常運作，請務必為使用者提供良好的錯誤處理程序和通訊，以便他們瞭解發生的情況，並盡可能修正。請務必考量可能的失敗情況，以及裝置會如何回應：如果使用者中斷執行中的工作，該怎麼辦？當使用者在離線時透過裝置要求動作時，該怎麼辦？規劃這些問題時可協助使用者解決問題，可避免使用者感到困擾，進而為您的裝置提供更優質的使用體驗。

本指南提供處理錯誤的意圖回應範例。請參閱錯誤和例外狀況一文，查看有效的 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 will prompt the user with "the device are not available right now" after receiving the response. Remember that you still need to send offline state for devices in report state after sending errorCode deviceOffline in EXECUTE response.

範例 2：EXECUTE 意圖的非封鎖例外狀況

使用者嘗試透過 Assistant 使用裝置鎖定前門的 Smart Lock。您可以成功控制其鎖定，但是發現裝置電量不足，因此執行要求會傳回包含 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 proactive notifications.

智慧型烘乾機正在運轉，有人在車門結束前將車門打開。 您可以呼叫 Google Home Graph API reportStateAndNotifications method to send a proactive notification with an 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 會在收到通知後提示使用者顯示「device 門已開啟」。您可以在相同的酬載中傳送對應的裝置狀態和通知。

範例 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，請參閱錯誤和例外狀況參考說明文件。