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

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

Ошибки

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

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

В итоге:

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

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

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

Онлайн и офлайн отчетность о состоянии

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

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

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

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