После совершения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия URL-адресов, включенных в ответ, истекает. Идентификатор мультимедийного элемента однозначно идентифицирует мультимедийный элемент, например фотографию или видео, в библиотеке пользователя.
Требуемые области авторизации
Для доступа к элементам мультимедиа, созданным приложением, требуется область данных photoslibrary.readonly.appcreateddata . Дополнительные сведения об областях см. в разделе Области авторизации .
Медиа-материалы
mediaItem — это представление мультимедиа, например фотографии или видео, которое было загружено в библиотеку Google Фото. Это объект верхнего уровня, и его свойства могут различаться в зависимости от базового типа носителя.
В следующей таблице перечислены свойства mediaItem :
| Характеристики | |
|---|---|
id | Постоянный, стабильный идентификатор, используемый для идентификации объекта. |
description | Описание медиа-объекта в Google Фото. |
baseUrl | Используется для доступа к необработанным байтам. Дополнительную информацию см. в разделе Базовые URL-адреса . |
productUrl | Ссылка на изображение внутри Google Фото. Эту ссылку не может открыть разработчик, только пользователь. URL-адреса указывают на элемент мультимедиа в библиотеке. Если URL-адрес был получен при поиске по альбому , он указывает на элемент в альбоме. |
mimeType | Тип элемента мультимедиа, позволяющий легко определить тип мультимедиа (например: image/jpg ). |
filename | Имя файла мультимедийного элемента, отображаемого пользователю в приложении Google Фото (в разделе информации об элементе). |
mediaMetadata | Зависит от основного типа носителя, например photo или video . Для уменьшения полезной нагрузки можно использовать маски полей. |
Получить медиа-материал
Чтобы получить элемент мультимедиа, вызовите mediaItems.get, используя mediaItemId . Запрос возвращает один медиа-элемент.
mediaItem содержит такие свойства, как идентификатор, описание и URL-адрес. Дополнительная информация на photo или video основана на метаданных в файле. Могут присутствовать не все свойства.
Если медиа-элементом является видео, сначала необходимо обработать видеофайл. mediaItem содержит поле status внутри mediaMetadata , которое описывает состояние обработки видеофайла. Недавно загруженный файл сначала возвращает videoProcessingStatus со значением PROCESSING , прежде чем он будет READY к использованию. baseUrl элемента мультимедиа видео недоступен до тех пор, пока видео не будет обработано.
Вот GET-запрос:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Beareroauth2-token
Ответ на элемент мультимедиа с фотографией выглядит следующим образом. Свойство photo содержит метаданные для элементов фотографий.
{
"id": "media-item-id ",
"description": "item-description ",
"productUrl": "url-to-open-in-google-photos ",
"baseUrl": "base-url_do-not-use-directly ",
"mimeType": "mime-type-of-media ",
"filename": "item-filename ",
"mediaMetadata": {
"width": "media-item-width ",
"height": "media-item-height ",
"creationTime": "media-item-creation-time ",
"photo": {
"cameraMake": "make-of-the-camera ",
"cameraModel": "model-of-the-camera ",
"focalLength": "focal-length-of-the-camera-lens ",
"apertureFNumber": "aperture-f-number-of-the-camera-lens ",
"isoEquivalent": "iso-of-the-camera ",
"exposureTime": "exposure-time-of-the-camera-aperture "
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly ",
"displayName": "name-of-user "
}
}
Ответ на элемент видеомедиа выглядит следующим образом. Свойство video содержит метаданные для элементов видео.
{
"id": "media-item-id ",
"description": "item-description ",
"productUrl": "url-to-open-in-google-photos ",
"baseUrl": "base-url_do-not-use-directly ",
"mimeType": "mime-type-of-media ",
"filename": "item-filename ",
"mediaMetadata": {
"width": "media-item-width ",
"height": "media-item-height ",
"creationTime": "media-item-creation-time ",
"video": {
"cameraMake": "make-of-the-camera ",
"cameraModel": "model-of-the-camera ",
"fps": "frame-rate-of-the-video ",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly ",
"displayName": "name-of-user "
}
}
Получить несколько медиа-элементов
Чтобы получить несколько элементов мультимедиа по их идентификаторам, вызовите mediaItems.batchGet используя mediaItemId s.
Запрос возвращает список MediaItemResults в порядке идентификаторов элементов мультимедиа, указанных в запросе. Каждый результат содержит MediaItem или Status , если произошла ошибка.
Максимальное количество медиа-элементов, которое вы можете запросить за один вызов, — 50. Список медиа-элементов не должен содержать повторяющихся идентификаторов и не может быть пустым.
Вот запрос GET, который показывает успешный и неудачный доступ к элементам мультимедиа. Укажите каждый идентификатор элемента мультимедиа в качестве нового параметра запроса mediaItemIds как часть запроса:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id &mediaItemIds=another-media-item-id &mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Beareroauth2-token
Запрос GET возвращает следующий ответ:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id ",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id ",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
Базовые URL-адреса
Базовые URL-адреса в API Google Фото предоставляют доступ к необработанным байтам мультимедийных элементов, позволяя вашему приложению загружать или отображать их. Эти URL-адреса включаются в ответы при перечислении альбомов или доступе к мультимедийным элементам. Помните, что для правильной работы базовых URL-адресов требуются дополнительные параметры.
Для API Picker:
Все объекты PickedMediaItem.mediaFileObjects включают baseUrl .
Базовые URL-адреса остаются активными в течение 60 минут, но срок их действия может истечь раньше, если пользователь отзовет разрешения вашего приложения через настройки своего аккаунта Google.
Для API библиотеки:
Базовые URL-адреса остаются активными в течение 60 минут.
Различные базовые URL-адреса:
-
baseUrl: прямой доступ к фотографии, миниатюре видео или загрузка байтов видео. -
coverPhotoBaseUrl: прямой доступ к обложке альбома. -
profilePictureBaseUrl: прямой доступ к фотографии профиля владельцаmediaItem.
Базовые URL-адреса изображений
Вот список опций, которые вы можете использовать с URL-адресами базовых изображений:
| Параметр | |
|---|---|
w , h | Описание Параметры ширины, Чтобы получить доступ к элементу мультимедиа изображения, например фотографии или миниатюре видео, необходимо указать размеры, которые вы планируете отображать в своем приложении (чтобы изображение можно было масштабировать до этих размеров, сохраняя при этом соотношение сторон). Для этого объедините базовый URL-адрес с необходимыми размерами, как показано в примерах. Примеры:
Вот пример отображения элемента мультимедиа шириной не более 2048 пикселей и высотой не более 1024 пикселей: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c | Описание Обрезка, параметр Если вы хотите обрезать изображение до точно указанных вами размеров ширины и высоты, объедините базовый URL-адрес с необязательным параметром Размер (в пикселях) должен находиться в диапазоне [1, 16383]. Если ширина или высота изображения превышает запрошенный размер, изображение уменьшается и обрезается (с сохранением соотношения сторон). Примеры:
В этом примере приложение отображает мультимедийный элемент шириной ровно 256 пикселей и высотой 256 пикселей, например миниатюру: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d | Описание Параметр загрузки, Если вы хотите загрузить изображение, сохранив все метаданные Exif, кроме метаданных местоположения, объедините базовый URL-адрес с параметром Примеры:
В этом примере приложение загружает изображение со всеми метаданными, кроме метаданных местоположения: https://lh3.googleusercontent.com/p/Az....XabC=d |
Базовые URL-адреса видео
Вот список опций, которые вы можете использовать с URL-адресами базы видео:
| Параметр | |
|---|---|
dv | Описание Чтобы получить доступ к байтам видео Параметр dv запрашивает высококачественную перекодированную версию исходного видео. Параметр несовместим с параметрами w и h . Базовые URL-адреса для загрузки видео могут возвращать байты в течение нескольких секунд. Прежде чем использовать этот параметр, убедитесь, что поле Примеры:
В следующем примере показано, как загрузить байты видео: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c и d | Описание Для доступа к миниатюре видео используйте любой из параметров URL-адреса базы изображения . По умолчанию все миниатюры видео содержат наложение кнопки воспроизведения. См. параметр -no , чтобы удалить это наложение. Примеры: Примеры см. в таблице базовых URL-адресов изображений . |
no | Описание Удаление наложения миниатюр, Если вы хотите получить миниатюру видео без наложения кнопки воспроизведения, объедините базовый URL-адрес с параметром no . Параметр no должен использоваться хотя бы с одним из параметров URL-адреса базы изображения . Примеры:
В следующем примере отображается миниатюра видео шириной ровно 1280 пикселей и высотой 720 пикселей без наложения кнопки воспроизведения: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Базовые URL-адреса движущихся фотографий
Анимированные фотографии содержат как фото, так и видеоэлементы. Вы можете использовать параметры из базовых URL-адресов изображений или базовых URL-адресов видео для запросов baseUrl движущихся фотографий.
| Параметр | |
|---|---|
dv | Описание Чтобы получить элемент видео из медиа-элемента движущейся фотографии, используйте параметр |
w , h , c и d | Описание Чтобы получить элемент фотографии из медиа-элемента движущейся фотографии, используйте формат базовых URL-адресов изображений . |