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

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

Ошибки

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

Коды ошибок могут быть прикреплены на уровне устройства или на глобальном уровне. Например, если у пользователя есть много источников света от одного провайдера и они контролируются концентратором, когда пользователь просит выключить все их источники света, провайдер может вернуть ошибку на уровне устройства, если один источник света отключен, или глобальный -уровня ошибка, если весь их хаб отключен и никакие источники света не могут управляться. Если все устройства отключены, нет никакой разницы между использованием ошибок глобального уровня или уровня устройства. Когда устройство находится в автономном режиме, вы должны сообщать о состоянии {"online": false} в reportState , даже если вы возвращаете код ошибки deviceOffline .

В итоге:

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

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

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

Неблокирующее исключение (УСПЕХ) о целевом устройстве

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

В замке передней двери разряжен аккумулятор. Запирание входной двери.

{
  "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 на устройстве.