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

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

Ошибки

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

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

Когда устройство находится в автономном режиме, вы должны сообщить {"online": false} в Report State в течение 5 минут после поведения устройства.

В итоге:

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

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

Следующий фрагмент 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"
  }
}

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

ЗАПРОС ответ

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

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

ВЫПОЛНИТЬ ответ

В следующем фрагменте 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"
            }
          }
        }
      }
    }
  }
}

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

Следующие ошибки приведут к созданию связанного TTS на устройстве.

Исключения

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

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

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

Если команда завершается неудачно из-за исключений, статус должен быть «ИСКЛЮЧЕНИЯ», а об исключениях следует сообщать с использованием признака 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"
          }
        ]
      }
    }
  }
}

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

Следующие исключения создают связанный TTS на устройстве.