Как создавать устройства и управлять ими

В этом руководстве рассказывается, как создавать устройства, управлять ими и удалять их. Правильное управление устройствами помогает обеспечить удобство использования и эффективное применение Ambient API.

Создание устройств

После того как пользователь успешно пройдет аутентификацию с помощью OAuth 2.0 для телевизоров и приложений на устройствах с ограниченными возможностями ввода, создайте устройство в его аккаунте Google Фото.

Когда ваше приложение успешно создает устройство с помощью метода devices.create, Ambient API возвращает объект AmbientDevice, который включает сгенерированный Google id. Надежно храните этот id и связывайте его со своими пользователями.

Упрощенное создание устройств с помощью OAuth

Ambient API предлагает упрощенный процесс OAuth. Если передать дополнительный параметр state в исходном запросе OAuth и вызвать devices.create с соответствующим значением requestId, можно связать процесс создания устройства непосредственно с процессом входа пользователя в аккаунт. Это упростит работу, поскольку пользователю нужно будет отсканировать меньше QR-кодов.

Подробную информацию и пример можно найти в руководстве Упрощенный процесс аутентификации для Ambient API.

Ограничения на количество устройств

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

Управление устройствами

После того как устройство создано и связано с аккаунтом Google Фото пользователя, вам может потребоваться управлять его жизненным циклом.

Получение информации об устройствах

Чтобы получить информацию об определенном устройстве, используйте метод devices.get с уникальным идентификатором id. Это полезно для проверки статуса устройства, например чтобы узнать, верно ли значение mediaSourcesSet.

Обновление устройств

Вы можете изменить некоторые свойства существующего устройства, например его отображаемое имя, с помощью метода devices.patch. Это позволяет пользователям персонализировать свои устройства и упрощает их идентификацию в Google Фото.

Удалить устройства

Разработайте стратегию удаления устройств, чтобы обеспечить надлежащую очистку и контроль со стороны пользователей. Удалить устройство можно с помощью метода devices.delete.

Рассмотрим следующие сценарии удаления устройств:

  • Отключение пользователя. Если пользователь отключает ваше приложение от аккаунта Google Фото, вы должны удалить соответствующее устройство.
  • Устройства, связь с которыми потеряна. Если вы потеряли устройство id, но у вас есть устройство requestId, которое использовалось при создании ключа, вы можете использовать устройство requestId с приложением devices.delete, чтобы удалить устройство, связь с которым потеряна. Это помогает избежать случайного дублирования и поддерживать порядок в аккаунте пользователя.

Важные примечания и рекомендации

  • Жизненный цикл устройства и авторизация пользователя. Вам нужно будет управлять жизненным циклом устройств и токенами авторизации пользователей. Учитывайте, как долго устройства остаются активными и как вы будете обрабатывать обновление токенов или повторную авторизацию, если устройство станет неактивным или срок действия его токена истечет.
  • Обработка ошибок. Реализуйте надежную обработку ошибок для всех вызовов API, связанных с устройствами. Будьте готовы к следующим ситуациям:
    • NOT_FOUND – если устройство не существует или не принадлежит пользователю.
    • RESOURCE_EXHAUSTED: если вы превысили ограничение на количество устройств.
    • ALREADY_EXISTS – если вы пытаетесь создать устройство с requestId, которое уже существует.

Дальнейшие действия