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

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

Ошибки

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

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

В итоге:

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

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

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