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

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

Создать Устройства

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

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

Важно: сохраните id . Если вы не сохраните сгенерированный Google id , вы не сможете получить устройство или управлять им позже. Это может привести к появлению бесхозных устройств в аккаунтах Google Photos ваших пользователей, к которым ваше приложение не сможет получить доступ или очистить их.

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

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

Более подробную информацию и пример см. в руководстве «Оптимизированный процесс аутентификации для API Ambient» .

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

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

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

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

Извлечь устройства

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

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

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

Примечание: Хорошей практикой является предоставление пользователю возможности назвать свое устройство перед его созданием. Это значительно упрощает для пользователя распознавание своего устройства при выборе медиа-элементов в его аккаунте Google Photos.

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

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

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

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

Важные соображения и передовой опыт

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

Следующие шаги

• Пример приложения: Наш пример приложения включает пример создания устройства и работы с данными ответа. Ознакомьтесь с функцией createDevice для получения дополнительной информации.
• Справочная документация: ознакомьтесь с подробной справочной документацией по устройствам для получения подробной информации обо всех доступных методах, параметрах запросов и ответов, а также кодах ошибок.
• Составление списка и извлечение элементов мультимедиа: после создания и управления устройствами научитесь составлять список и извлекать элементы мультимедиа для отображения на них.