После выполнения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия URL-адресов, включенных в ответ, истекает. Идентификатор мультимедийного элемента однозначно идентифицирует мультимедийный элемент, например фотографию или видео, в библиотеке пользователя.
Обратите внимание, что ваше приложение не должно кэшировать фотографию или видео пользователя в течение длительного периода времени, но в зависимости от вашего варианта использования вы можете хранить или кэшировать идентификатор мультимедийного элемента столько , сколько необходимо . Также следует отметить, что доступ к пользовательским данным регулируется обязательствами по обеспечению конфиденциальности.
Требуемые области авторизации
Для доступа к элементам мультимедиа ваше приложение должно запросить хотя бы одну из следующих областей авторизации . Доступ к элементам мультимедиа, возвращенным в ответе, зависит от запрошенных вами областей.
-
photoslibrary.readonly
разрешает доступ ко всем медиа-элементам в библиотеке пользователя. -
photoslibrary.readonly.appcreateddata
разрешает доступ только к медиа-элементам, созданным приложением.
Медиа-материалы
mediaItem
— это представление мультимедиа, например фотографии или видео, которое было загружено в библиотеку Google Фото. Это объект верхнего уровня, и его свойства могут различаться в зависимости от базового типа носителя.
В следующей таблице перечислены свойства mediaItem
:
Характеристики | |
---|---|
id | Постоянный, стабильный идентификатор, используемый для идентификации объекта. |
description | Описание медиа-объекта в Google Фото. |
baseUrl | Используется для доступа к необработанным байтам. Дополнительную информацию см. в разделе Базовые URL-адреса . |
productUrl | Ссылка на изображение внутри Google Фото. Эту ссылку не может открыть разработчик, только пользователь. URL-адреса указывают на элемент мультимедиа в библиотеке. Если URL-адрес был получен при поиске по альбому , он указывает на элемент в альбоме. |
mimeType | Тип элемента мультимедиа, позволяющий легко определить тип мультимедиа (например: image/jpg ). |
filename | Имя файла мультимедийного элемента, отображаемого пользователю в приложении Google Фото (в разделе информации об элементе). |
mediaMetadata | Зависит от основного типа носителя, например photo или video . Для уменьшения полезной нагрузки можно использовать маски полей. |
contributorInfo | Это поле заполняется только в том случае, если элемент мультимедиа находится в общем альбоме, созданном этим приложением, и пользователь предоставил область Содержит информацию об авторе, который добавил этот медиа-элемент. Дополнительные сведения см. в разделе Общий доступ к медиафайлам . |
Получить медиа-материал
Чтобы получить элемент мультимедиа, вызовите mediaItems.get, используя mediaItemId
. Запрос возвращает один элемент мультимедиа.
mediaItem
содержит такие свойства, как идентификатор, описание и URL-адрес. Дополнительная информация на photo
или video
основана на метаданных в файле. Не все свойства могут присутствовать. ContributorInfo
содержит метаданные для элементов, которые являются частью общего альбома. Это поле включается только при перечислении содержимого общего альбома, для которого пользователь предоставил область авторизации photoslibrary.sharing
.
Если медиа-элементом является видео, сначала необходимо обработать видеофайл. mediaItem
содержит поле status
внутри mediaMetadata
, которое описывает состояние обработки видеофайла. Недавно загруженный файл сначала возвращает videoProcessingStatus
со значением PROCESSING
, прежде чем он будет READY
к использованию. baseUrl
элемента мультимедиа видео недоступен до тех пор, пока видео не будет обработано.
ОТДЫХ
Вот GET-запрос:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-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" } }
Ява
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Получить несколько медиа-элементов
Чтобы получить несколько элементов мультимедиа по их идентификаторам, вызовите 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: Bearer oauth2-token
Запрос GET возвращает следующий ответ:
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Ява
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Базовые URL-адреса
Базовые URL-адреса в API библиотеки Google Фото позволяют вам получить доступ к байтам элементов мультимедиа. Используя различные базовые URL-адреса, ваше приложение может либо загружать элементы мультимедиа, либо отображать их в вашем приложении. Базовые URL-адреса — это строки, которые включаются в ответ при перечислении альбомов или доступе к элементам мультимедиа. Они действительны в течение 60 минут и требуют дополнительных параметров, поскольку их нельзя использовать как есть.
Различные базовые URL-адреса:
-
baseUrl
: прямой доступ к фотографии, миниатюре видео или загрузка видеобайтов. -
coverPhotoBaseUrl
: прямой доступ к обложке альбома. -
profilePictureBaseUrl
: прямой доступ к фотографии профиля владельцаmediaItem
.
Базовые URL-адреса изображений
Вот список опций, которые вы можете использовать с URL-адресами базовых изображений:
Параметр | |
---|---|
w , h | Описание Параметры ширины, Чтобы получить доступ к элементу мультимедиа изображения, например фотографии или миниатюре видео, необходимо указать размеры, которые вы планируете отображать в своем приложении (чтобы изображение можно было масштабировать до этих размеров, сохраняя при этом соотношение сторон). Для этого объедините базовый URL-адрес с необходимыми размерами, как показано в примерах. Примеры: base-url=wmax-width-hmax-height Вот пример отображения элемента мультимедиа шириной не более 2048 пикселей и высотой не более 1024 пикселей: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c | Описание Обрезка, параметр Если вы хотите обрезать изображение до точно указанных вами размеров ширины и высоты, объедините базовый URL-адрес с необязательным параметром Размер (в пикселях) должен находиться в диапазоне [1, 16383]. Если ширина или высота изображения превышает запрошенный размер, изображение уменьшается и обрезается (с сохранением соотношения сторон). Примеры: base-url=wmax-width-hmax-height-c В этом примере приложение отображает мультимедийный элемент шириной ровно 256 пикселей и высотой 256 пикселей, например миниатюру: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d | Описание Параметр загрузки, Если вы хотите загрузить изображение, сохранив все метаданные Exif, кроме метаданных местоположения, объедините базовый URL-адрес с параметром Примеры: base-url=d В этом примере приложение загружает изображение со всеми метаданными, кроме метаданных местоположения: https://lh3.googleusercontent.com/p/Az....XabC=d |
Базовые URL-адреса видео
Вот список опций, которые вы можете использовать с URL-адресами базы видео:
Параметр | |
---|---|
dv | Описание Чтобы получить доступ к байтам видео Параметр dv запрашивает высококачественную перекодированную версию исходного видео. Параметр несовместим с параметрами w и h . Базовые URL-адреса для загрузки видео могут возвращать байты в течение нескольких секунд. Прежде чем использовать этот параметр, убедитесь, что поле Примеры: base-url=dv В следующем примере показано, как загрузить байты видео: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c и d | Описание Для доступа к миниатюре видео используйте любой из параметров URL-адреса базы изображения . По умолчанию все миниатюры видео содержат наложение кнопки воспроизведения. См. параметр -no , чтобы удалить это наложение. Примеры: Примеры см. в таблице базовых URL-адресов изображений . |
no | Описание Удаление наложения миниатюр, Если вы хотите получить миниатюру видео без наложения кнопки воспроизведения, объедините базовый URL-адрес с параметром no . Параметр no должен использоваться хотя бы с одним из параметров URL-адреса базы изображения . Примеры: base-url=wmax-width-hmax-height-no В следующем примере отображается миниатюра видео шириной ровно 1280 пикселей и высотой 720 пикселей без наложения кнопки воспроизведения: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Базовые URL-адреса движущихся фотографий
Анимированные фотографии содержат как фото, так и видеоэлементы. Вы можете использовать параметры из базовых URL-адресов изображений или базовых URL-адресов видео для запросов baseUrl
движущихся фотографий.
Параметр | |
---|---|
dv | Описание Чтобы получить элемент видео из медиа-элемента движущейся фотографии, используйте параметр |
w , h , c и d | Описание Чтобы получить элемент фотографии из медиа-элемента движущейся фотографии, используйте формат базовых URL-адресов изображений . |
После выполнения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия URL-адресов, включенных в ответ, истекает. Идентификатор мультимедийного элемента однозначно идентифицирует мультимедийный элемент, например фотографию или видео, в библиотеке пользователя.
Обратите внимание, что ваше приложение не должно кэшировать фотографию или видео пользователя в течение длительного периода времени, но в зависимости от вашего варианта использования вы можете хранить или кэшировать идентификатор мультимедийного элемента столько , сколько необходимо . Также следует отметить, что доступ к пользовательским данным регулируется обязательствами по обеспечению конфиденциальности.
Требуемые области авторизации
Для доступа к элементам мультимедиа ваше приложение должно запросить хотя бы одну из следующих областей авторизации . Доступ к элементам мультимедиа, возвращенным в ответе, зависит от запрошенных вами областей.
-
photoslibrary.readonly
разрешает доступ ко всем медиа-элементам в библиотеке пользователя. -
photoslibrary.readonly.appcreateddata
разрешает доступ только к медиа-элементам, созданным приложением.
Медиа-материалы
mediaItem
— это представление мультимедиа, например фотографии или видео, которое было загружено в библиотеку Google Фото. Это объект верхнего уровня, и его свойства могут различаться в зависимости от базового типа носителя.
В следующей таблице перечислены свойства mediaItem
:
Характеристики | |
---|---|
id | Постоянный, стабильный идентификатор, используемый для идентификации объекта. |
description | Описание медиа-объекта в Google Фото. |
baseUrl | Используется для доступа к необработанным байтам. Дополнительную информацию см. в разделе Базовые URL-адреса . |
productUrl | Ссылка на изображение внутри Google Фото. Эту ссылку не может открыть разработчик, только пользователь. URL-адреса указывают на элемент мультимедиа в библиотеке. Если URL-адрес был получен при поиске по альбому , он указывает на элемент в альбоме. |
mimeType | Тип элемента мультимедиа, позволяющий легко определить тип мультимедиа (например: image/jpg ). |
filename | Имя файла мультимедийного элемента, отображаемого пользователю в приложении Google Фото (в разделе информации об элементе). |
mediaMetadata | Зависит от основного типа носителя, например photo или video . Для уменьшения полезной нагрузки можно использовать маски полей. |
contributorInfo | Это поле заполняется только в том случае, если элемент мультимедиа находится в общем альбоме, созданном этим приложением, и пользователь предоставил область Содержит информацию об авторе, который добавил этот медиа-элемент. Дополнительные сведения см. в разделе Общий доступ к медиафайлам . |
Получить медиа-материал
Чтобы получить элемент мультимедиа, вызовите mediaItems.get, используя mediaItemId
. Запрос возвращает один элемент мультимедиа.
mediaItem
содержит такие свойства, как идентификатор, описание и URL-адрес. Дополнительная информация на photo
или video
основана на метаданных в файле. Не все свойства могут присутствовать. ContributorInfo
содержит метаданные для элементов, которые являются частью общего альбома. Это поле включается только при перечислении содержимого общего альбома, для которого пользователь предоставил область авторизации photoslibrary.sharing
.
Если медиа-элементом является видео, сначала необходимо обработать видеофайл. mediaItem
содержит поле status
внутри mediaMetadata
, которое описывает состояние обработки видеофайла. Недавно загруженный файл сначала возвращает videoProcessingStatus
со значением PROCESSING
, прежде чем он будет READY
к использованию. baseUrl
элемента мультимедиа видео недоступен до тех пор, пока видео не будет обработано.
ОТДЫХ
Вот GET-запрос:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-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" } }
Ява
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Получить несколько медиа-элементов
Чтобы получить несколько элементов мультимедиа по их идентификаторам, вызовите 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: Bearer oauth2-token
Запрос GET возвращает следующий ответ:
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Ява
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Базовые URL-адреса
Базовые URL-адреса в API библиотеки Google Фото позволяют вам получить доступ к байтам элементов мультимедиа. Используя различные базовые URL-адреса, ваше приложение может либо загружать элементы мультимедиа, либо отображать их в вашем приложении. Базовые URL-адреса — это строки, которые включаются в ответ при перечислении альбомов или доступе к элементам мультимедиа. Они действительны в течение 60 минут и требуют дополнительных параметров, поскольку их нельзя использовать как есть.
Различные базовые URL-адреса:
-
baseUrl
: прямой доступ к фотографии, миниатюре видео или загрузка видеобайтов. -
coverPhotoBaseUrl
: прямой доступ к обложке альбома. -
profilePictureBaseUrl
: прямой доступ к фотографии профиля владельцаmediaItem
.
Базовые URL-адреса изображений
Вот список опций, которые вы можете использовать с URL-адресами базовых изображений:
Параметр | |
---|---|
w , h | Описание Параметры ширины, Чтобы получить доступ к элементу мультимедиа изображения, например фотографии или миниатюре видео, необходимо указать размеры, которые вы планируете отображать в своем приложении (чтобы изображение можно было масштабировать до этих размеров, сохраняя при этом соотношение сторон). Для этого объедините базовый URL-адрес с необходимыми размерами, как показано в примерах. Примеры: base-url=wmax-width-hmax-height Вот пример отображения элемента мультимедиа шириной не более 2048 пикселей и высотой не более 1024 пикселей: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c | Описание Обрезка, параметр Если вы хотите обрезать изображение до точно указанных вами размеров ширины и высоты, объедините базовый URL-адрес с необязательным параметром Размер (в пикселях) должен находиться в диапазоне [1, 16383]. Если ширина или высота изображения превышает запрошенный размер, изображение уменьшается и обрезается (с сохранением соотношения сторон). Примеры: base-url=wmax-width-hmax-height-c В этом примере приложение отображает мультимедийный элемент шириной ровно 256 пикселей и высотой 256 пикселей, например миниатюру: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d | Описание Параметр загрузки, Если вы хотите загрузить изображение, сохранив все метаданные Exif, кроме метаданных местоположения, объедините базовый URL-адрес с параметром Примеры: base-url=d В этом примере приложение загружает изображение со всеми метаданными, кроме метаданных местоположения: https://lh3.googleusercontent.com/p/Az....XabC=d |
Базовые URL-адреса видео
Вот список опций, которые вы можете использовать с URL-адресами базы видео:
Параметр | |
---|---|
dv | Описание Чтобы получить доступ к байтам видео Параметр dv запрашивает высококачественную перекодированную версию исходного видео. Параметр несовместим с параметрами w и h . Базовые URL-адреса для загрузки видео могут возвращать байты в течение нескольких секунд. Прежде чем использовать этот параметр, убедитесь, что поле Примеры: base-url=dv В следующем примере показано, как загрузить байты видео: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c и d | Описание Для доступа к миниатюре видео используйте любой из параметров URL-адреса базы изображения . По умолчанию все миниатюры видео содержат наложение кнопки воспроизведения. См. параметр -no , чтобы удалить это наложение. Примеры: Примеры см. в таблице базовых URL-адресов изображений . |
no | Описание Удаление наложения миниатюр, Если вы хотите получить миниатюру видео без наложения кнопки воспроизведения, объедините базовый URL-адрес с параметром no . Параметр no должен использоваться хотя бы с одним из параметров URL-адреса базы изображения . Примеры: base-url=wmax-width-hmax-height-no В следующем примере отображается миниатюра видео шириной ровно 1280 пикселей и высотой 720 пикселей без наложения кнопки воспроизведения: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Базовые URL-адреса движущихся фотографий
Анимированные фотографии содержат как фото, так и видеоэлементы. Вы можете использовать параметры из базовых URL-адресов изображений или базовых URL-адресов видео для запросов baseUrl
движущихся фотографий.
Параметр | |
---|---|
dv | Описание Чтобы получить элемент видео из медиа-элемента движущейся фотографии, используйте параметр |
w , h , c и d | Описание Чтобы получить элемент фотографии из медиа-элемента движущейся фотографии, используйте формат базовых URL-адресов изображений . |
После выполнения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия URL-адресов, включенных в ответ, истекает. Идентификатор мультимедийного элемента однозначно идентифицирует мультимедийный элемент, например фотографию или видео, в библиотеке пользователя.
Обратите внимание, что ваше приложение не должно кэшировать фотографию или видео пользователя в течение длительного периода времени, но в зависимости от вашего варианта использования вы можете хранить или кэшировать идентификатор мультимедийного элемента столько , сколько необходимо . Также следует отметить, что доступ к пользовательским данным регулируется обязательствами по обеспечению конфиденциальности.
Требуемые области авторизации
Для доступа к элементам мультимедиа ваше приложение должно запросить хотя бы одну из следующих областей авторизации . Доступ к элементам мультимедиа, возвращенным в ответе, зависит от запрошенных вами областей.
-
photoslibrary.readonly
разрешает доступ ко всем медиа-элементам в библиотеке пользователя. -
photoslibrary.readonly.appcreateddata
разрешает доступ только к медиа-элементам, созданным приложением.
Медиа-материалы
mediaItem
— это представление мультимедиа, например фотографии или видео, которое было загружено в библиотеку Google Фото. Это объект верхнего уровня, и его свойства могут различаться в зависимости от базового типа носителя.
В следующей таблице перечислены свойства mediaItem
:
Характеристики | |
---|---|
id | Постоянный, стабильный идентификатор, используемый для идентификации объекта. |
description | Описание медиа-объекта в Google Фото. |
baseUrl | Используется для доступа к необработанным байтам. Дополнительную информацию см. в разделе Базовые URL-адреса . |
productUrl | Ссылка на изображение внутри Google Фото. Эту ссылку не может открыть разработчик, только пользователь. URL-адреса указывают на элемент мультимедиа в библиотеке. Если URL-адрес был получен при поиске по альбому , он указывает на элемент в альбоме. |
mimeType | Тип элемента мультимедиа, позволяющий легко определить тип мультимедиа (например: image/jpg ). |
filename | Имя файла мультимедийного элемента, отображаемого пользователю в приложении Google Фото (в разделе информации об элементе). |
mediaMetadata | Зависит от основного типа носителя, например photo или video . Для уменьшения полезной нагрузки можно использовать маски полей. |
contributorInfo | Это поле заполняется только в том случае, если элемент мультимедиа находится в общем альбоме, созданном этим приложением, и пользователь предоставил область Содержит информацию об авторе, который добавил этот медиа-элемент. Дополнительные сведения см. в разделе Общий доступ к медиафайлам . |
Получить медиа-материал
Чтобы получить элемент мультимедиа, вызовите mediaItems.get, используя mediaItemId
. Запрос возвращает один элемент мультимедиа.
mediaItem
содержит такие свойства, как идентификатор, описание и URL-адрес. Дополнительная информация на photo
или video
основана на метаданных в файле. Не все свойства могут присутствовать. ContributorInfo
содержит метаданные для элементов, которые являются частью общего альбома. Это поле включается только при перечислении содержимого общего альбома, для которого пользователь предоставил область авторизации photoslibrary.sharing
.
Если медиа-элементом является видео, сначала необходимо обработать видеофайл. mediaItem
содержит поле status
внутри mediaMetadata
, которое описывает состояние обработки видеофайла. Недавно загруженный файл сначала возвращает videoProcessingStatus
со значением PROCESSING
, прежде чем он будет READY
к использованию. baseUrl
элемента мультимедиа видео недоступен до тех пор, пока видео не будет обработано.
ОТДЫХ
Вот GET-запрос:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-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" } }
Ява
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Получить несколько медиа-элементов
Чтобы получить несколько элементов мультимедиа по их идентификаторам, вызовите 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: Bearer oauth2-token
Запрос GET возвращает следующий ответ:
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Ява
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Базовые URL-адреса
Базовые URL-адреса в API библиотеки Google Фото позволяют вам получить доступ к байтам элементов мультимедиа. Используя различные базовые URL-адреса, ваше приложение может либо загружать элементы мультимедиа, либо отображать их в вашем приложении. Базовые URL-адреса — это строки, которые включаются в ответ при перечислении альбомов или доступе к элементам мультимедиа. Они действительны в течение 60 минут и требуют дополнительных параметров, поскольку их нельзя использовать как есть.
Различные базовые URL-адреса:
-
baseUrl
: прямой доступ к фотографии, миниатюре видео или загрузка видеобайтов. -
coverPhotoBaseUrl
: прямой доступ к обложке альбома. -
profilePictureBaseUrl
: прямой доступ к фотографии профиля владельцаmediaItem
.
Базовые URL-адреса изображений
Вот список опций, которые вы можете использовать с URL-адресами базовых изображений:
Параметр | |
---|---|
w , h | Описание Параметры ширины, Чтобы получить доступ к элементу мультимедиа изображения, например фотографии или миниатюре видео, необходимо указать размеры, которые вы планируете отображать в своем приложении (чтобы изображение можно было масштабировать до этих размеров, сохраняя при этом соотношение сторон). Для этого объедините базовый URL-адрес с необходимыми размерами, как показано в примерах. Примеры: base-url=wmax-width-hmax-height Вот пример отображения элемента мультимедиа шириной не более 2048 пикселей и высотой не более 1024 пикселей: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c | Описание Обрезка, параметр Если вы хотите обрезать изображение до точно указанных вами размеров ширины и высоты, объедините базовый URL-адрес с необязательным параметром Размер (в пикселях) должен находиться в диапазоне [1, 16383]. Если ширина или высота изображения превышает запрошенный размер, изображение уменьшается и обрезается (с сохранением соотношения сторон). Примеры: base-url=wmax-width-hmax-height-c В этом примере приложение отображает мультимедийный элемент шириной ровно 256 пикселей и высотой 256 пикселей, например миниатюру: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d | Описание Параметр загрузки, Если вы хотите загрузить изображение, сохранив все метаданные Exif, кроме метаданных местоположения, объедините базовый URL-адрес с параметром Примеры: base-url=d В этом примере приложение загружает изображение со всеми метаданными, кроме метаданных местоположения: https://lh3.googleusercontent.com/p/Az....XabC=d |
Базовые URL-адреса видео
Вот список опций, которые вы можете использовать с URL-адресами базы видео:
Параметр | |
---|---|
dv | Описание Чтобы получить доступ к байтам видео Параметр dv запрашивает высококачественную перекодированную версию исходного видео. Параметр несовместим с параметрами w и h . Базовые URL-адреса для загрузки видео могут возвращать байты в течение нескольких секунд. Прежде чем использовать этот параметр, убедитесь, что поле Примеры: base-url=dv В следующем примере показано, как загрузить байты видео: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c и d | Описание Для доступа к миниатюре видео используйте любой из параметров URL-адреса базы изображения . По умолчанию все миниатюры видео содержат наложение кнопки воспроизведения. См. параметр -no , чтобы удалить это наложение. Примеры: Примеры см. в таблице базовых URL-адресов изображений . |
no | Описание Удаление наложения миниатюр, Если вы хотите получить миниатюру видео без наложения кнопки воспроизведения, объедините базовый URL-адрес с параметром no . Параметр no должен использоваться хотя бы с одним из параметров URL-адреса базы изображения . Примеры: base-url=wmax-width-hmax-height-no В следующем примере отображается миниатюра видео шириной ровно 1280 пикселей и высотой 720 пикселей без наложения кнопки воспроизведения: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Базовые URL-адреса движущихся фотографий
Анимированные фотографии содержат как фото, так и видеоэлементы. Вы можете использовать параметры из базовых URL-адресов изображений или базовых URL-адресов видео для запросов baseUrl
движущихся фотографий.
Параметр | |
---|---|
dv | Описание Чтобы получить элемент видео из медиа-элемента движущейся фотографии, используйте параметр |
w , h , c и d | Описание Чтобы получить элемент фотографии из медиа-элемента движущейся фотографии, используйте формат базовых URL-адресов изображений . |
После выполнения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия URL-адресов, включенных в ответ, истекает. Идентификатор мультимедийного элемента однозначно идентифицирует мультимедийный элемент, например фотографию или видео, в библиотеке пользователя.
Обратите внимание, что ваше приложение не должно кэшировать фотографию или видео пользователя в течение длительного периода времени, но в зависимости от вашего варианта использования вы можете хранить или кэшировать идентификатор мультимедийного элемента столько , сколько необходимо . Также следует отметить, что доступ к пользовательским данным регулируется обязательствами по обеспечению конфиденциальности.
Требуемые области авторизации
Для доступа к элементам мультимедиа ваше приложение должно запросить хотя бы одну из следующих областей авторизации . Доступ к элементам мультимедиа, возвращенным в ответе, зависит от запрошенных вами областей.
-
photoslibrary.readonly
разрешает доступ ко всем медиа-элементам в библиотеке пользователя. -
photoslibrary.readonly.appcreateddata
разрешает доступ только к медиа-элементам, созданным приложением.
Медиа-материалы
mediaItem
— это представление мультимедиа, например фотографии или видео, которое было загружено в библиотеку Google Фото. Это объект верхнего уровня, и его свойства могут различаться в зависимости от базового типа носителя.
В следующей таблице перечислены свойства mediaItem
:
Характеристики | |
---|---|
id | Постоянный, стабильный идентификатор, используемый для идентификации объекта. |
description | Описание медиа-объекта в Google Фото. |
baseUrl | Используется для доступа к необработанным байтам. Дополнительную информацию см. в разделе Базовые URL-адреса . |
productUrl | Ссылка на изображение внутри Google Фото. Эту ссылку не может открыть разработчик, только пользователь. URL-адреса указывают на элемент мультимедиа в библиотеке. Если URL-адрес был получен при поиске по альбому , он указывает на элемент в альбоме. |
mimeType | Тип элемента мультимедиа, позволяющий легко определить тип мультимедиа (например: image/jpg ). |
filename | Имя файла мультимедийного элемента, отображаемого пользователю в приложении Google Фото (в разделе информации об элементе). |
mediaMetadata | Зависит от основного типа носителя, например photo или video . Для уменьшения полезной нагрузки можно использовать маски полей. |
contributorInfo | Это поле заполняется только в том случае, если элемент мультимедиа находится в общем альбоме, созданном этим приложением, и пользователь предоставил область Содержит информацию об авторе, который добавил этот медиа-элемент. Дополнительные сведения см. в разделе Общий доступ к медиафайлам . |
Получить медиа-материал
Чтобы получить элемент мультимедиа, вызовите mediaItems.get, используя mediaItemId
. Запрос возвращает один элемент мультимедиа.
mediaItem
содержит такие свойства, как идентификатор, описание и URL-адрес. Дополнительная информация на photo
или video
основана на метаданных в файле. Не все свойства могут присутствовать. ContributorInfo
содержит метаданные для элементов, которые являются частью общего альбома. Это поле включается только при перечислении содержимого общего альбома, для которого пользователь предоставил область авторизации photoslibrary.sharing
.
Если медиа-элементом является видео, сначала необходимо обработать видеофайл. mediaItem
содержит поле status
внутри mediaMetadata
, которое описывает состояние обработки видеофайла. Недавно загруженный файл сначала возвращает videoProcessingStatus
со значением PROCESSING
, прежде чем он будет READY
к использованию. baseUrl
элемента мультимедиа видео недоступен до тех пор, пока видео не будет обработано.
ОТДЫХ
Вот GET-запрос:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-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" } }
Ява
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
Свойство photo содержит метаданные для элементов фотографий.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Свойство video содержит метаданные для элементов видео.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Получить несколько медиа-элементов
Чтобы получить несколько элементов мультимедиа по их идентификаторам, вызовите 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: Bearer oauth2-token
Запрос GET возвращает следующий ответ:
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Ява
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Базовые URL-адреса
Базовые URL-адреса в API библиотеки Google Фото позволяют вам получить доступ к байтам элементов мультимедиа. Используя различные базовые URL-адреса, ваше приложение может либо загружать элементы мультимедиа, либо отображать их в вашем приложении. Базовые URL-адреса — это строки, которые включаются в ответ при перечислении альбомов или доступе к элементам мультимедиа. Они действительны в течение 60 минут и требуют дополнительных параметров, поскольку их нельзя использовать как есть.
Различные базовые URL-адреса:
-
baseUrl
: прямой доступ к фотографии, миниатюре видео или загрузка видеобайтов. -
coverPhotoBaseUrl
: прямой доступ к обложке альбома. -
profilePictureBaseUrl
: прямой доступ к фотографии профиля владельцаmediaItem
.
Базовые URL-адреса изображений
Вот список опций, которые вы можете использовать с URL-адресами базовых изображений:
Параметр | |
---|---|
w , h | Описание Параметры ширины, Чтобы получить доступ к элементу мультимедиа изображения, например фотографии или миниатюре видео, необходимо указать размеры, которые вы планируете отображать в своем приложении (чтобы изображение можно было масштабировать до этих размеров, сохраняя при этом соотношение сторон). Для этого объедините базовый URL-адрес с необходимыми размерами, как показано в примерах. Примеры: base-url=wmax-width-hmax-height Вот пример отображения элемента мультимедиа шириной не более 2048 пикселей и высотой не более 1024 пикселей: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c | Описание Обрезка, параметр Если вы хотите обрезать изображение до точно указанных вами размеров ширины и высоты, объедините базовый URL-адрес с необязательным параметром Размер (в пикселях) должен находиться в диапазоне [1, 16383]. Если ширина или высота изображения превышает запрошенный размер, изображение уменьшается и обрезается (с сохранением соотношения сторон). Примеры: base-url=wmax-width-hmax-height-c В этом примере приложение отображает мультимедийный элемент шириной ровно 256 пикселей и высотой 256 пикселей, например миниатюру: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d | Описание Параметр загрузки, Если вы хотите загрузить изображение, сохранив все метаданные Exif, кроме метаданных местоположения, объедините базовый URL-адрес с параметром Примеры: base-url=d В этом примере приложение загружает изображение со всеми метаданными, кроме метаданных местоположения: https://lh3.googleusercontent.com/p/Az....XabC=d |
Базовые URL-адреса видео
Вот список опций, которые вы можете использовать с URL-адресами базы видео:
Параметр | |
---|---|
dv | Описание Чтобы получить доступ к байтам видео Параметр dv запрашивает высококачественную перекодированную версию исходного видео. Параметр несовместим с параметрами w и h . Базовые URL-адреса для загрузки видео могут возвращать байты в течение нескольких секунд. Прежде чем использовать этот параметр, убедитесь, что поле Примеры: base-url=dv В следующем примере показано, как загрузить байты видео: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c и d | Описание Для доступа к миниатюре видео используйте любой из параметров URL-адреса базы изображения . По умолчанию все миниатюры видео содержат наложение кнопки воспроизведения. См. параметр -no , чтобы удалить это наложение. Примеры: Примеры см. в таблице базовых URL-адресов изображений . |
no | Описание Удаление наложения миниатюр, Если вы хотите получить миниатюру видео без наложения кнопки воспроизведения, объедините базовый URL-адрес с параметром no . Параметр no должен использоваться хотя бы с одним из параметров URL-адреса базы изображения . Примеры: base-url=wmax-width-hmax-height-no В следующем примере отображается миниатюра видео шириной ровно 1280 пикселей и высотой 720 пикселей без наложения кнопки воспроизведения: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Базовые URL-адреса движущихся фотографий
Анимированные фотографии содержат как фото, так и видеоэлементы. Вы можете использовать параметры из базовых URL-адресов изображений или базовых URL-адресов видео для запросов baseUrl
движущихся фотографий.
Параметр | |
---|---|
dv | Описание Чтобы получить элемент видео из медиа-элемента движущейся фотографии, используйте параметр |
w , h , c и d | Описание Чтобы получить элемент фотографии из медиа-элемента движущейся фотографии, используйте формат базовых URL-адресов изображений . |