Lỗi và ngoại lệ

Tài liệu này liệt kê các lỗi và trường hợp ngoại lệ được hỗ trợ chính thức cho các thiết bị nhà thông minh. Vui lòng sử dụng các mã lỗi và ngoại lệ nhất định này trong phản hồi ý định hoặc trong thông báo nếu bạn đã triển khai mã này để Trợ lý Google cảnh báo người dùng cuối về các vấn đề liên quan đến một lệnh hoặc trạng thái thiết bị nhất định. Nếu phản hồi chứa định dạng không chính xác hoặc errorCode, Trợ lý Google sẽ hiển thị cho người dùng một thông báo lỗi chung, chẳng hạn như "Rất tiếc, hiện tại, thiết bị chưa có sẵn".

Lỗi

Bạn nên trả về mã lỗi khi vấn đề khiến thực thi hoặc yêu cầu truy vấn thất bại. Ví dụ: nếu khoá cửa bị kẹt và không khoá được hoặc không khoá, thì người dùng sẽ được trả về lỗi về trạng thái này.

Mã lỗi có thể được đính kèm ở cấp thiết bị hoặc ở cấp toàn cầu. Ví dụ: nếu người dùng có nhiều đèn từ một nhà cung cấp và các thiết bị đó do một trung tâm điều khiển, thì khi người dùng yêu cầu tắt tất cả đèn, nhà cung cấp có thể trả về lỗi cấp thiết bị nếu một đèn không kết nối mạng hoặc lỗi toàn cục nếu toàn bộ trung tâm của họ ở chế độ ngoại tuyến và không thể điều khiển đèn. Nếu tất cả các thiết bị đều không có kết nối mạng, sẽ không có sự khác biệt giữa việc sử dụng lỗi chung hoặc ở cấp độ thiết bị. Khi thiết bị không có kết nối mạng, bạn nên báo cáo trạng thái {"online": false} trong reportState ngay cả khi bạn trả về mã lỗi deviceOffline.

Tóm tắt:

• Lỗi cấp toàn cục: tất cả các thiết bị trong phản hồi đều có cùng một lỗi
• Lỗi cấp địa phương: phản hồi hỗn hợp với lỗi và trường hợp thành công

Lỗi cấp toàn cầu

Đoạn mã JSON sau đây cho thấy cách bạn trả về các lỗi cấp toàn cục trong phản hồi QUERY hoặc EXECUTE.

Một ví dụ về lỗi deviceOffline toàn cục do trung tâm thực hiện việc ngoại tuyến:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

Dưới đây là một ví dụ về lỗi inSoftwareUpdate toàn cục do trung tâm cập nhật:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

Lỗi cấp thiết bị

QUERY câu trả lời

Đoạn mã JSON sau đây cho biết cách bạn trả về lỗi cấp thiết bị trong phản hồi QUERY.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

Thực thi phản hồi

Đoạn mã JSON sau đây cho biết cách bạn trả về các lỗi ở cấp thiết bị trong phản hồi EXECUTE (Thực thi chính sách).

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

Thông báo có lỗi

Thông báo chủ động

Đoạn mã JSON sau đây cho biết cách bạn báo cáo lỗi cấp thiết bị trong một thông báo chủ động.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

Phản hồi tiếp theo

Đoạn mã JSON sau đây cho biết cách bạn báo cáo lỗi cấp thiết bị trong một phản hồi tiếp theo.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

Danh sách lỗi

Các lỗi sau sẽ tạo TTS được liên kết trên thiết bị.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}