Ошибки и исключения

В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Используйте эти коды ошибок и исключений в ответе на намерение или в уведомлениях, если вы их реализовали, чтобы Google Ассистент сообщал конечным пользователям о проблемах, связанных с определенной командой или состоянием устройства. Если в ответе неправильное форматирование или errorCode, Google Ассистент показывает пользователям общее сообщение об ошибке, например "Извините, устройство сейчас недоступно".

Ошибки

Если при выполнении запроса execute или query возникает проблема, необходимо вернуть код ошибки. Например, если замок заклинило и его нельзя открыть или закрыть, пользователю нужно сообщить об ошибке.

Коды ошибок можно прикреплять на уровне устройства или на глобальном уровне. Например, если у пользователя много светильников от одного поставщика, которые управляются через концентратор, то при запросе на отключение всех светильников поставщик может вернуть ошибку на уровне устройства, если один из светильников не подключен к сети, или ошибку на глобальном уровне, если концентратор не подключен к сети и ни одним светильником нельзя управлять. Если все устройства офлайн, то нет разницы между ошибками на уровне устройства и на глобальном уровне.

Сводные указания:

• Ошибка на уровне всего ответа: все устройства в ответе имеют одну и ту же ошибку.
• Ошибка на уровне локального ответа: смешанный ответ с ошибками и успешными случаями

Ошибки на глобальном уровне

В приведенном ниже фрагменте кода JSON показано, как возвращать ошибки на уровне глобального домена в ответе QUERY или EXECUTE.

Пример ошибки deviceOffline на уровне устройства из-за того, что контроллер офлайн:

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

Пример ошибки inSoftwareUpdate на уровне аккаунта из-за обновления центра:

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

Ошибки на уровне устройства

Ответ функции QUERY

В приведенном ниже фрагменте JSON показано, как возвращать ошибки на уровне устройства в ответе на запрос.

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

Ответ EXECUTE

В приведенном ниже фрагменте кода JSON показано, как возвращать ошибки на уровне устройства в ответе 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
        }
      }
    ]
  }
}

Уведомления с ошибками

Упреждающее уведомление

В приведенном ниже фрагменте кода JSON показано, как сообщать об ошибках на уровне устройства в проактивном уведомлении.

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

Дополнительный ответ

В приведенном ниже фрагменте кода JSON показано, как сообщить об ошибках на уровне устройства в последующем ответе.

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

Список ошибок

При возникновении перечисленных ниже ошибок на устройстве будет воспроизводиться соответствующий текст.

Отчеты о статусе онлайн и офлайн

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Исключения

Исключение следует возвращать, если с командой связана проблема или оповещение. Команда может быть выполнена успешно или с ошибкой.

Если команда выполнена успешно (статус = "SUCCESS"), сообщите об исключениях, используя признак StatusReport (для устройств, отличных от целевого), или вернув соответствующий exceptionCode (для целевого устройства).

Например, если фильтр сушильной машины заполнен, пользователь все равно может запустить ее, но вы можете предупредить его об этом. Аналогично, если батарея устройства разряжена, но не полностью, вы можете выполнить команду, но должны сообщить пользователю, что батарея устройства разряжена.

Если команда не выполняется из-за исключений, статус должен быть EXCEPTIONS, а исключения должны быть указаны с помощью свойства StatusReport.

Неблокирующее исключение (SUCCESS) для целевого устройства

Вот пример блокировки двери:

Низкий заряд батареи замка на входной двери. Закрываю входную дверь.

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

Неблокирующее исключение (SUCCESS) о другом устройстве, использующем StatusReport

Пример для включения охранной системы: Хорошо, включаю охранную систему. Переднее окно открыто.

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

Исключение блокировки, связанное с другим устройством, использующим 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"
          }
        ]
      }
    }
  }
}

Список исключений

В следующих случаях на устройстве будет воспроизводиться соответствующий текст.