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 đối với các thiết bị thông minh trong nhà. Vui lòng sử dụng các mã lỗi và ngoại lệ sau đâ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 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 có định dạng không chính xác hoặc errorCode, thì 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 sử dụng được".

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 yêu cầu 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ầu. Ví dụ: nếu người dùng có nhiều đèn từ một trì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, trì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 cấp độ toàn cầu nếu toàn bộ trung tâm của họ không 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ì việc sử dụng lỗi cấp toàn cầu hoặc cấp thiết bị không có sự khác biệt. Khi thiết bị không 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ầ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 với các trường hợp lỗi và thành công

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

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

Một ví dụ về lỗi cấp độ toàn cầu deviceOffline do trung tâm này đ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ầu inSoftwareUpdate do trung tâm này đ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ề các 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 nối tiếp

Đ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 sẽ tạo 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 xảy ra sự cố hoặc cảnh báo liên quan đến 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 = "FAILED"), 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à thiết bị 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ị sắp hết pin và chưa hết pin, bạn vẫn có thể thực thi lệnh nhưng nên cho thiết bị biết pin của thiết bị sắp hết.

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.

Ngoại lệ không chặn (THÀNH CÔNG) về thiết bị mục tiêu

Ví dụ sau đây là về việc 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 (HUỶ) về thiết bị khác sử dụng StatusReport

Ví dụ sau đây minh hoạ cách bật hệ thống an ninh: Tôi đang bật hệ thống an ninh. Cử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ề thiết bị khác bằng cách 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 TTS được liên kết trên thiết bị.