Lỗi và ngoại lệ

Tài liệu này liệt kê các lỗi và 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 thông báo. Nhờ đó, 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 phản hồi chứa định dạng không chính xác hoặc errorCode, Trợ lý Google sẽ đưa ra 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á/mở khoá, thì bạn phải trả lại 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ục. Ví dụ: nếu người dùng có nhiều đèn từ một nhà cung cấp và các đèn đó được điều khiển bằng một trung tâm, 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 có kết nối mạng hoặc lỗi cấp toàn cục nếu toàn bộ trung tâm 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 ở chế độ ngoại tuyến, thì việc sử dụng lỗi cấp toàn cục hay cấp thiết bị sẽ không có gì khác biệt.

Khi thiết bị không kết nối mạng, bạn nên báo cáo {"online": false} để Báo cáo trạng thái trong vòng 5 phút kể từ hành vi của thiết bị.

Tóm tắt:

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

Lỗi cấp toàn cục

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

Ví dụ về lỗi cấp toàn cục deviceOffline do trung tâm đang ngoại tuyến:

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

Ví dụ về lỗi cấp toàn cục 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ị

Phản hồi QUERY

Đ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 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 cho biết 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 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"
          }
        }
      }
    }
  }
}

Câu trả lời tiếp theo

Đoạn mã JSON sau đây minh hoạ cách bạn báo cáo các 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 TTS được liên kết trên thiết bị.

Ngoại lệ

Bạn nên trả về một 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 đặc điểm StatusReport (đối với các thiết bị không phải là 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 lưới lọc bụi 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 họ về trạng thái này. Tương tự, khi pin của thiết bị yếu nhưng chưa hết, bạn vẫn có thể thực thi lệnh nhưng phải cho họ biết pin của thiết bị đang yếu.

Nếu lệnh không thực hiện được do các trường hợp ngoại lệ, thì trạng thái sẽ là "EXCEPTIONS" và các trường hợp ngoại lệ phải được báo cáo bằng tính năng StatusReport.

Trường hợp ngoại lệ không chặn (THÀNH CÔNG) về thiết bị mục tiêu

Ví dụ này là để khoá cửa:

Khoá cửa trước yếu pin. Đ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

Ví dụ này là để kích hoạt hệ thống an ninh: Ok, kích hoạ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"
        }]
      }
    }]
  }
}

Chặn ngoại lệ về một thiết bị khác bằ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 đây sẽ tạo ra TTS được liên kết trên thiết bị.