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

Общий

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

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. Подробнее см. в разделе «Ошибки и исключения» .