處理錯誤和例外狀況

如果裝置或要求無法正常運作，請務必提供良好的錯誤處理機制和通訊功能，讓使用者瞭解發生什麼問題，並盡可能提供修正方法。請務必仔細思考可能發生的失敗情況，以及裝置應如何回應：如果使用者中斷進行中的工作，該怎麼辦？如果使用者在裝置離線時要求執行動作，該怎麼辦？預先規劃這些問題並協助使用者復原，可避免使用者感到挫折，並為裝置打造更優質的體驗。

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

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

使用者在客廳安裝了兩盞智慧型燈具，使用者下達「打開客廳燈」指令，Google 隨即傳送 EXECUTE 意圖至執行網址。您發現使用者的裝置離線且無法控制，因此執行要求會傳回 EXECUTE 回應，其中包含 status ERROR 和 errorCode deviceOffline。

以下範例說明如何從燈具裝置傳回含有 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 鎖上前門的智慧門鎖。你可以成功控制鎖，但發現裝置電池電量不足，因此執行要求會傳回 EXECUTE 回應，其中包含 status SUCCESS 和 exceptionCode lowBattery。

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