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 thiết bị nhà thông minh. Vui lòng sử dụng các lỗi và mã ngoại lệ đã cho này trong phản hồi ý định hoặc trong thông báo nếu bạn đã triển khai ý định. Như vậy, Trợ lý Google sẽ 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 câu trả lời chứa định dạng không chính xác hoặc errorCode, Trợ lý Google sẽ gửi cho người dùng một thông báo lỗi chung, ví dụ: "Rất tiếc, thiết bị hiện không hoạt động".

Lỗi

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

Bạn có thể đính kèm mã lỗi ở 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à họ được một trung tâm kiểm soát, 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 đèn đơn lẻ không có kết nối mạng, hoặc lỗi cấp toàn cầu nếu toàn bộ trung tâm của họ không có kết nối mạng và không thể điều khiển đèn nào. Nếu tất cả các thiết bị đều không kết nối mạng, thì không có sự khác biệt giữa việc sử dụng lỗi cấp toàn cầu hoặc lỗi 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 trả về mã lỗi deviceOffline.

Tóm tắt:

• Lỗi toàn cầu: tất cả thiết bị trong phản hồi đều có cùng một lỗi
• Lỗi cấp cục bộ: phản hồi hỗn hợp kèm theo 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 minh hoạ cách bạn trả về lỗi cấp toàn cầu trong phản hồi QUERY hoặc EXECUTE.

Ví dụ về lỗi cấp toàn cầu deviceOffline do trung tâm đang không kết nối mạng:

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

Ví dụ về lỗi cấp toàn cầu inSoftwareUpdate do trung tâm đang cập nhật:

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

Lỗi ở cấp thiết bị

Câu trả lời QUERY

Đoạn mã JSON sau đây cho thấy 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"
      }
    }
  }
}

EXECUTE phản hồi

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

{
  "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 các 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 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 đây sẽ tạo ra tính năng TTS được liên kết trên thiết bị.

Trường hợp ngoại lệ

Bạn nên trả về một trường hợp ngoại lệ khi có vấn đề hoặc cảnh báo liên quan đến một lệnh. Lệnh này có thể thành công hoặc không thành công.

Nếu lệnh thành công (trạng thái = "SUCCESS"), hãy báo cáo các trường hợp ngoại lệ bằng cách sử dụng trait StatusReport (đối với các thiết bị không phải mục tiêu) hoặc bằng cách trả về một exceptionCode thích hợp (đối với thiết bị mục tiêu).

Ví dụ: nếu màn hình tìm lỗi mã nguồn của máy sấy đầy, người dùng vẫn có thể khởi động máy sấy, nhưng bạn nên cảnh báo cho họ về trạng thái này. Tương tự, khi thiết bị vẫn còn pin và chưa sử dụng hết pin, bạn vẫn có thể thực thi lệnh nhưng phải cho thiết bị biết pin thiết bị sắp hết.

Nếu lệnh không thành công do có ngoại lệ, trạng thái sẽ là "ExceptionS" và các ngoại lệ phải được báo cáo bằng trait StatusReport.

Ngoại lệ không chặn (SUCCESS) về thiết bị mục tiêu

Sau đây là ví dụ về cách khoá cửa:

Khoá cửa trước sắp hết pin. Tôi đang khoá cửa trước.

{
  "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"
      }
    }]
  }
}

Ngoại lệ không chặn (SUCCESS) về một thiết bị khác sử dụng StatusReport

Sau đây là ví dụ về cách bật hệ thống an ninh: Ok, bật hệ thống an ninh. Cửa sổ phía trước đang mở.

{
  "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"
        }]
      }
    }]
  }
}

Ngoại lệ chặn đối với một thiết bị khác sử dụng StatusReport

{
  "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"
          }
        ]
      }
    }
  }
}

Danh sách ngoại lệ

Các trường hợp ngoại lệ sau sẽ tạo ra tính năng TTS được liên kết trên thiết bị.