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

В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Пожалуйста, используйте эти коды ошибок и исключений в ответе о намерениях или в уведомлениях , если вы их реализовали, чтобы 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 на устройстве.

В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Пожалуйста, используйте эти коды ошибок и исключений в ответе о намерениях или в уведомлениях , если вы их реализовали, чтобы 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 на устройстве.

Exceptions

You should return an exception when there is an issue or alert associated with a command. The command could succeed or fail.

If the command was successful (status = "SUCCESS"), report exceptions using the StatusReport trait (for devices other than the target), or by returning an appropriate exceptionCode (for the target device).

For example, if the dryer lint screen is full the user can still start their dryer, but you may want to warn them about this state. Similarly, when a device has a low battery that is not empty, you can still execute a command but should let them know that the device battery is low.

If the command fails due to exceptions, the status should be "EXCEPTIONS", and the exceptions should be reported using the StatusReport trait.

Non-blocking exception (SUCCESS) about target device

This example is for locking the door:

The front door lock has low battery. Locking the front door.

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

Non-blocking exception (SUCCESS) about another device using StatusReport

This example is for arming a security system: Ok, arming the security system. The front window is open.

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

Blocking exception about another device using 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"
          }
        ]
      }
    }
  }
}

Exception list

The following exceptions will produce the associated TTS on the device.