调用 列出某个照片库或影集的内容 而不是存储返回的媒体项,而是应存储 媒体项的 ID。这是因为媒体项的内容 并且响应中包含的网址会在一段时间后过期。通过 媒体项 ID 是媒体项(如照片或视频)的唯一标识符 自己用户的内容库中的内容
请注意,您的应用不应长时间缓存用户的照片或视频 但根据您的使用场景,您可能会存储或 缓存媒体内容 ID, long 为 必要。 另请注意,访问用户 数据受隐私权约束 义务。
必需的授权范围
如要访问媒体内容,您的应用必须请求至少以下一项: 授权范围。 对响应中返回的媒体内容的访问权限取决于您 请求。
photoslibrary.readonly
可允许访问用户账号中的所有媒体内容 库- “
photoslibrary.readonly.appcreateddata
”仅允许访问符合以下条件的媒体内容: 由相关应用创建
媒体项
答
mediaItem
是上传到
Google 相册媒体库。它是顶级对象,其属性可以
因底层媒体类型而异。
下表列出了 mediaItem
属性:
属性 | |
---|---|
id |
用于标识对象的永久性固定 ID。 |
description |
媒体内容的内景说明 Google 相册。 |
baseUrl |
用于访问原始字节。如需了解详情,请参阅基准网址。 |
productUrl |
指向 Google 相册中图片的链接。此链接不能是 且只能由用户打开网址指向 库。如果该网址是从影集搜索中检索到的,则 指向影集内的内容。 |
mimeType |
媒体项的类型,有助于轻松识别媒体类型
(例如:image/jpg )。 |
filename |
Google 相册中向用户显示的媒体内容的文件名 (在商品的信息部分中)。 |
mediaMetadata |
因媒体的基础类型而异,例如 photo
或 video 。
为减少负载,可使用字段掩码。
|
contributorInfo |
仅当媒体内容位于共享影集中时,系统才会填充此字段
并且用户已授予
包含有关添加此媒体的贡献者的信息 内容。有关详情,请参阅分享媒体内容。 |
获取媒体内容
要检索媒体项,请调用
mediaItems.get,使用
mediaItemId
。该请求会返回单个媒体内容。
mediaItem
包含 ID、说明和网址等属性。通过
photo
或 video
中的额外信息基于以下项中的元数据:
文件。并非所有属性都存在。ContributorInfo
包含元数据
。只有在以下情况下才会包含此字段:
列出
用户已授予photoslibrary.sharing
权限的共享影集
授权范围。
如果媒体内容是视频,则必须先处理视频文件。通过
mediaItem
在 mediaMetadata
中包含 status
字段,用于描述
视频文件的处理状态。新上传的文件会返回
videoProcessingStatus
其值是 PROCESSING
,其后再使用 READY
。baseUrl
视频媒体项的字幕在视频处理完成之前不可用。
REST
以下是一个 GET 请求:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
照片媒体内容的响应如下所示。照片 属性包含照片项的元数据。
{ "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" } }
视频媒体内容的响应如下所示。视频 属性包含视频内容的元数据。
{ "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" } }
Java
照片属性包含照片内容的元数据。
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 }
视频属性包含视频内容的元数据。
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
照片属性包含照片内容的元数据。
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 }
视频属性包含视频内容的元数据。
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
。
该请求会返回
MediaItemResults
按照请求中提供的媒体内容标识符的顺序进行排列。每条结果
包含 MediaItem
如果出现错误,则返回 Status
。
一次调用中最多可请求 50 项媒体内容。 媒体内容不得包含重复的标识符,也不得为空。
REST
以下是一个 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." } } ] }
Java
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 }
基本网址
借助 Google Photos Library API 中的基准网址,您可以访问媒体内容的字节 项。借助各种基准网址,您的应用可以下载媒体内容 或在应用中显示媒体项。基本网址是 会包含在响应中。它们分别是 有效期为 60 分钟,并且需要额外的参数,因为它们不能用作 。
下面列出了各种基准网址:
baseUrl
:直接访问视频的照片、缩略图或下载视频字节。coverPhotoBaseUrl
:直接访问影集的封面照片。profilePictureBaseUrl
:直接访问mediaItem
。
映像基准网址
以下是可与图片基准网址搭配使用的选项列表:
参数 | |
---|---|
w 、h |
说明 宽度 如需访问图片媒体内容(例如照片或缩略图),请执行以下操作: 您必须指定计划以何种尺寸展示 以便将图片缩放到 尺寸,同时保持宽高比)。为此, 将基准网址与所需的维度进行连接,如 示例。 示例: base-url=wmax-width-hmax-height 以下示例显示了宽度不超过 2048 像素且高度不超过 1024 像素: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
说明 剪裁 如果您想要将图片剪裁为精确的宽度和高度
将基准网址与
可选的 大小(以像素为单位)应在 [1, 16383] 范围内。如果其中任一情况 图片的宽度或高度,超出请求的尺寸, 缩小和剪裁图片(保持宽高比)。 示例: base-url=wmax-width-hmax-height-c 在此示例中,应用显示的媒体内容是 正好 256 像素宽,256 像素高,例如 缩略图: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
说明 下载内容的 如果您想下载保留所有 Exif 元数据的图片
(位置元数据除外),请将基准网址与
示例: base-url=d 在此示例中,应用下载包含全部 (位置元数据除外): https://lh3.googleusercontent.com/p/Az....XabC=d |
视频基准网址
以下是您可以对视频基准网址使用的选项列表:
参数 | |
---|---|
dv |
说明 如需访问视频 dv 参数请求的是高品质 原始视频的转码版本。参数不是 与 w 和 h 兼容 参数。 视频下载基准网址最多可能需要几秒钟的时间才能 返回字节数。视频下载内容默认采用 H.264 编码。如果 H.264 编码失败,将使用 VP9。 在使用此参数之前,请检查媒体内容的
“ 示例: base-url=dv 以下示例展示了如何下载 视频: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w 、h 、c 和
d |
说明 要访问视频的缩略图,请使用任意图片基准网址参数。 默认情况下,所有视频缩略图都会叠加播放某次视频 按钮。要删除此叠加层,请参阅 -no 参数。 示例: 请参阅映像基准网址表格 获取示例。 |
no |
说明 移除缩略图叠加层的 如果您想检索没有叠加层的视频缩略图 时,请将基准网址与no 参数。 no 参数必须至少与以下项之一配合使用 该 图片基准网址参数。 示例: base-url=wmax-width-hmax-height-no 以下示例显示的视频缩略图正好为 1280 px(宽)x 720 px(高),并且不包含播放按钮叠加层: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
动态照片基准网址
动态照片同时包含照片和视频元素。您可以使用
图片基准网址或
用于动态照片 baseUrl
请求的视频基准网址。
参数 | |
---|---|
dv |
说明 如需检索动态照片媒体项的视频元素,请使用
|
w 、h 、c 和
d |
说明 如需检索动态照片媒体项的照片元素,请使用 图片基准网址的格式。 |