После совершения вызовов для вывода списка содержимого библиотеки фотографий или альбома вместо сохранения возвращенных элементов мультимедиа ваше приложение должно сохранять идентификаторы элементов мультимедиа. Это связано с тем, что содержимое элементов мультимедиа может измениться, и через определенное время срок действия 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-адресов изображений . |