通过调用列出照片库或影集的内容后，您的应用应存储媒体内容的 ID，而不是存储返回的媒体内容。这是因为媒体内容的内容可能会发生变化，并且响应中包含的网址会在一段时间后过期。媒体内容 ID 是媒体内容（如用户媒体库中的照片或视频）的唯一标识符。
请注意，您的应用不应长时间缓存用户的照片或视频，但您可以根据用例，根据需要存储或缓存媒体内容 ID。您还应注意的是，对用户数据的访问受隐私权义务的约束。
必需的授权范围
如需访问媒体内容，您的应用必须至少请求以下一项授权范围。对响应中返回的媒体内容的访问权限取决于您请求的范围。
photoslibrary.readonly允许访问用户媒体库中的所有媒体内容photoslibrary.readonly.appcreateddata仅允许访问应用创建的媒体内容
媒体项
mediaItem 表示已上传到 Google 相册媒体库的媒体内容（例如照片或视频）。它是顶级对象，其属性可能会因底层媒体类型而异。
下表列出了 mediaItem 属性：
| 属性 | |
|---|---|
id |
用于标识对象的永久性固定 ID。 |
description |
Google 相册中显示的媒体内容说明。 |
baseUrl |
用于访问原始字节。如需了解详情，请参阅基准网址。 |
productUrl |
指向 Google 相册内图片的链接。开发者无法打开此链接，只能由用户打开。网址指向媒体库中的媒体内容。如果该网址是从影集搜索中检索到的，则该网址指向影集中的内容。 |
mimeType |
媒体项的类型，有助于轻松识别媒体类型（例如：image/jpg）。 |
filename |
Google 相册应用中向用户显示的媒体内容文件名（位于内容的信息部分）。 |
mediaMetadata |
因媒体的底层类型而异，例如 photo 或 video。
如需减少载荷，可以使用字段掩码。 |
contributorInfo |
仅当媒体内容位于此应用创建的共享影集中且用户已授予 包含添加此媒体项的贡献者的相关信息。有关详情，请参阅分享媒体内容。 |
获取媒体内容
如需检索媒体内容，请使用 mediaItemId 调用 mediaItems.get。该请求会返回单个媒体内容。
mediaItem 包含 ID、说明和网址等属性。photo 或 video 中的其他信息基于文件中的元数据。并非所有属性都存在。ContributorInfo 包含属于共享影集的内容的元数据。只有在用户已授予 photoslibrary.sharing
授权范围的共享影集中列出内容时，才会包含此字段。
如果媒体内容是视频，则必须先处理视频文件。mediaItem 在 mediaMetadata 内包含一个 status 字段，用于描述视频文件的处理状态。新上传的文件首先会返回值为 PROCESSING 的 videoProcessingStatus，然后才能使用 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
}
获取多个媒体项
如需按标识符检索多个媒体内容，请使用 mediaItemId 调用 mediaItems.batchGet。
该请求会按照请求中提供的媒体内容标识符的顺序返回 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 px（宽）x 256 px（高）的媒体内容，如缩略图： 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 参数不兼容。 视频下载的基准网址最多可能需要几秒钟的时间才能返回字节。 在使用此参数之前，请检查媒体内容的 示例： 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 像素、高度为 720 像素的视频缩略图，而且不包含播放按钮叠加层： https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
动态照片基准网址
动态照片同时包含照片和视频元素。您可以将图片基准网址或视频基准网址中的参数用于动态照片 baseUrl 请求。
| 参数 | |
|---|---|
dv |
说明 如需检索动态照片媒体内容的视频元素，请使用 |
w、h、c 和 d |
说明 如需检索动态照片媒体内容的照片元素，请使用图片基准网址的格式。 |