Умный дом: часто задаваемые вопросы

Общий

В: Где и на каком языке нам следует реализовать нашу инфраструктуру обработки заказов «из облака в облако»?

A: При условии поддержки современных протоколов SSL (TLS) и OAuth 2.0 вы можете реализовать свою инфраструктуру на любой платформе и на любом языке по вашему выбору. Мы рекомендуем развернуть её как можно ближе к остальной инфраструктуре, чтобы повысить надёжность и сократить задержку выполнения на реальных пользовательских устройствах.

В: Должны ли идентификаторы устройств быть уникальными?

О: Идентификаторы должны быть уникальными. Если в вашем сервисе нет уникальных идентификаторов, они должны быть уникальными хотя бы на уровне пользователя. Представьте себе пользователя с несколькими домами, и оба дома интегрированы с одним и тем же пользователем. Запрос на включение света в одном доме не должен включать свет с тем же идентификатором в другом доме.

В: Должны ли имена устройств быть уникальными?

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

Вот краткое руководство по именованию:

  • Имена должны быть такими, которые люди действительно могут произнести.
  • Мы распознаем подмножества строк, поэтому если у вас есть «acme color light», мы также ответим на «acme light».
  • Мы приветствуем как описательное название продукта, так и одно или несколько имен, определяемых пользователем.
  • Пользователям не нужно давать названия комнатам со светильниками, потому что у нас для этого есть комнаты; у них должны быть уникальные названия для каждой комнаты, но они всегда могут использовать множественное число для управления всем (например, две лампочки в офисных бра — «северный свет» и «восточный свет», но их можно называть просто «светильники»).

В: Как часто обновляется состояние устройства?

A: Эфемерное состояние извлекается по запросу QUERY или EXECUTE, которые инициируются пользователем. Если пользователь спрашивает: «Включен ли свет?» или хочет сделать свет ярче, нам потребуется выполнить запрос, чтобы определить текущее состояние.

В: Можно ли обновить Home Graph напрямую, указав текущее состояние устройства?

A: Да, используйте вызов API Report State .

Привязка аккаунтов и OAuth

A: Да, для подключения устройств пользователя к облачным сервисам провайдера требуется привязка учетной записи.

В: Для OAuth срок действия токенов доступа истекает каждые 15,213 часов. Это нормально?

О: Да, но, пожалуйста, протестируйте с достаточно коротким сроком действия, например, 10–20 минут. Наш OAuth-клиент должен обновлять токены по мере необходимости, и тестирование с коротким сроком действия подтвердит работоспособность этого подхода.

Намерения

В: Когда происходит SYNC?

A: SYNC происходит сразу после завершения OAuth и после выполнения вызова Request Sync .

В: Почему не работает SYNC ?

A: Существует ряд распространенных причин, по которым это может не сработать.

  • Вы отправляете неправильные типы устройств.

    • Например, мы ожидаем action.devices.types.LIGHT , но вы отправляете action.devices.types.Light .

  • Вы отправляете неподдерживаемые типы устройств.

    • Например, вы отправляете action.devices.types.FLASHLIGHT — мы не поддерживаем такую возможность.

  • Вы отправляете недопустимые/неподдерживаемые поля.

    • Например, у вас есть поле, которого нет в нашей спецификации.

  • В вашем ответе SYNC обнаружена другая проблема форматирования.

    • Проверьте скобки!

  • У вас возникла проблема с привязкой аккаунта.

    • Убедитесь, что вы получаете действительный токен доступа в заголовке Auth запроса SYNC.

  • Вы слишком долго отвечаете на запрос SYNC.

    • Пожалуйста, убедитесь, что вы отвечаете на запрос SYNC в течение 5 секунд.

В: Допустим ли ответ «в ожидании»?

О: Мы настоятельно рекомендуем использовать ответ «успешно/неуспешно», а не «ожидание», если ваши устройства доступны в режиме реального времени. Свяжитесь с нами, если вам нужен ответ «ожидание» — мы понимаем, что некоторым маломощным устройствам, не работающим в режиме реального времени, может потребоваться ответ «ожидание» и асинхронная модель выполнения.

Тестирование и отправка

В: Можно ли настроить облачную среду разработки?

A: Да, вы можете протестировать незапущенную облачную среду и конфигурацию.

В: Моё действие не отображается в разделе «Управление домом» приложения Google Home. Что происходит?

A: Подтвердите, что вы являетесь разработчиком этого проекта.

Отчет о состоянии

В: Существуют ли предпосылки для внедрения Report State?

A: Проект должен использовать API умного дома, поддерживать OAuth2 и иметь признаки, имеющие состояния, которые необходимо сообщать.

В: Как часто нам нужно отправлять отчет о состоянии устройства?

О: Google интересуют переходное и конечное состояние. Однако, если за короткий промежуток времени происходит много изменений состояния (например, пользователь три раза открывает и закрывает холодильник в течение минуты или переключает диммер), нам нужно сообщить только конечное состояние.

В: Нужно ли отправлять полную информацию о состоянии устройства при выполнении вызовов «Отчет о состоянии»?

A: Частичные обновления состояния не поддерживаются, поэтому вызовы Report State всегда должны включать все данные по конкретному обновлённому признаку. Если два признака приводят к несоответствию, их следует сообщать вместе.

В: Может ли Google отправлять запросы моему устройству, чтобы узнать его состояние (то есть опрашивать устройство)?

О: Это резервный механизм, который мы не рекомендуем использовать. Если нам потребуется часто опрашивать устройство для этих пользователей, мы не можем гарантировать, какой будет дополнительная нагрузка. Необходимость обусловлена новыми визуальными поверхностями. Помимо проблемы с неизвестной нагрузкой, это ухудшит пользовательский опыт. Мы считаем, что Report State критически важна для платформы.

В: Какие характеристики поддерживают Report State прямо сейчас?

A: Поддерживаются все публичные характеристики, с которыми связаны состояния. Также следует сообщать о любых изменениях в состоянии «Онлайн» устройства.

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

В: Требуется ли для отчета о состоянии отправлять временную метку?

A: Нам не требуется временная метка; последнее отправленное состояние переопределит предыдущие вызовы.

В: Нужно ли мне отдельно сообщать состояние, если я уже отправляю состояние в запросе и/или выполнении?

A: Home Graph сохраняет только состояние, отправленное через Report State . Состояние, возвращаемое в ответ на намерения EXECUTE и QUERY, используется только для речевых ответов пользователю и не сохраняется. Поэтому Report State следует вызывать, даже если новое состояние устройства уже было возвращено в ответ на намерение EXECUTE или QUERY.

В: Каковы последствия, если Report State не будет полностью реализован в установленные сроки?

О: Это приведёт к ухудшению пользовательского опыта, например, в Google Home app (GHA) и на визуальных поверхностях. Это означает, что будет отправлено много запросов на определение состояния, и мы не можем гарантировать, что это повлияет на дополнительную нагрузку на облако партнёра.

В: Как я могу протестировать реализацию нашей функции «Состояние отчета»?

A: Используйте Home Graph Viewer — инструмент самостоятельного тестирования, который показывает текущие состояния вашего устройства, сохраненные в Home Graph .

В: Можно ли использовать случайный requestId для отчета о состоянии?

A: Мы рекомендуем партнерам использовать тот же requestId, который они получили из запроса EXECUTE, если Report State инициировано запросом EXECUTE, в противном случае вы можете просто использовать случайный requestId.

В: Если у пользователя несколько устройств и состояние одного из них изменилось, должны ли мы сообщать последнее состояние всех устройств?

О: Нет. Вам нужно сообщить только состояние конкретного устройства.

Лучшие практики

В: Какая задержка приемлема?

О: Менее 200 мс — идеальный вариант, от 2 до 5 с — приемлемый вариант. Если задержка составляет около 5 секунд, свяжитесь с нами.

В: Как сделать так, чтобы голосовое управление моего динамика корректно реагировало, когда он не в сети?

A: Возвращаем состояние «офлайн» для устройств, не подключенных к сети. Для этой ошибки мы возвращаем «недоступно сейчас» в качестве текста в формате TTS. Подробнее см. в разделе «Ошибки и исключения» .