Начните работу с API Ambient

API Ambient позволяет вашему приложению подключать внешние устройства к учетной записи пользователя Google Фото и отображать выбранные им фотографии.

Поток API Ambient

Ниже приведено описание того, как работает Ambient API для подключения устройства, а затем извлечения и отображения элементов мультимедиа:

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

  2. Инициируйте авторизацию OAuth 2.0 (и при необходимости создайте устройство): начните процесс авторизации OAuth 2.0 для телевизоров и устройств с ограниченными возможностями ввода, запросив код авторизации.

  3. Создание нового устройства: Ваше приложение создает устройство в аккаунте Google Фото пользователя, вызывая CreateDevice и предоставляя действительный UUID v4.

    После успешного создания устройства API вернет объект AmbientDevice , содержащий назначенный Google deviceId . Для вашего приложения крайне важно сохранить этот deviceId и связать его с вашими пользователями.

  4. Отображение settingsUri : объект AmbientDevice включает settingsUri . Предоставьте этот URI пользователю, обычно в виде QR-кода, который пользователь может отсканировать с помощью своего мобильного устройства. Этот URI направляет пользователя в приложение Google Photos, где он может настроить источники мультимедиа (например, альбомы), которые он хочет отображать на своем внешнем устройстве.

  5. Опрос mediaSourcesSet : Ваше приложение должно периодически вызывать метод GetDevice , предоставляя deviceId , чтобы проверить состояние окружающего устройства. Отслеживайте поле mediaSourcesSet в ответе AmbientDevice . Изначально оно будет иметь значение false.

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

    Ответ AmbientDevice включает pollingConfig с pollInterval , который следует использовать в качестве ориентира для частоты опроса.

  6. Извлечение элементов мультимедиа: когда mediaSourcesSet возвращает значение true, ваше приложение может начать извлечение элементов мультимедиа, выбранных пользователем.

    Вызовите метод ListMediaItems , указав deviceId . API вернет ListMediaItemsResponse , содержащий список объектов AmbientMediaItem . Каждый AmbientMediaItem включает такие данные, как id , createTime и объект MediaFile с дополнительными метаданными. MediaFile содержит baseUrl , который можно использовать для извлечения фактических байтов элемента мультимедиа. Ознакомьтесь с руководством по списку и извлечению элементов мультимедиа для получения подробной информации о дополнительных параметрах baseUrl .

  7. Отображение элементов мультимедиа: используйте baseUrl из MediaFile для загрузки и отображения медиаконтента на внешнем устройстве.

Важные соображения

Ограничение и управление устройством:

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

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

Работа с медиа-элементами:

  • Использование медиа-элемента: узнайте, как правильно извлекать и обрабатывать содержимое медиа-элемента с помощью baseUrl , включая необходимую аутентификацию или параметры.
  • Обработка ошибок: реализуйте надежную обработку ошибок для вызовов API, включая такие сценарии, как NOT_FOUND для устройств, FAILED_PRECONDITION если источники мультимедиа не установлены, и RESOURCE_EXHAUSTED если достигнуты ограничения устройств.

Дополнительные сведения см. в руководстве по составлению списка и извлечению элементов мультимедиа .

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