访问媒体内容

通过调用列出照片库或影集内容后，您的应用应存储媒体内容的 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

仅当媒体内容位于此应用创建的共享影集中且用户已授予 photoslibrary.sharing 范围时，系统才会填充此字段。

包含有关添加此媒体的贡献者的信息 内容。有关详情，请参阅分享媒体内容。

获取媒体内容

要检索媒体项，请调用 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
}

获取多项媒体内容

如需按标识符检索多项媒体内容，请使用 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

说明

宽度参数 w 和高度参数 h。

如需访问图片媒体内容（例如照片或缩略图），请执行以下操作： 您必须指定计划以何种尺寸展示 以便将图片缩放到 尺寸，同时保持宽高比）。为此， 将基准网址与所需的维度进行连接，如 示例。

示例：

base-url=wmax-width-hmax-height

以下示例显示了宽度不超过 2048 像素且高度不超过 1024 像素：

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

说明

剪裁参数 c。

如果您想将图片剪裁为您指定的准确宽度和高度，请将基准网址与可选参数 -c 以及强制参数 w 和 h 进行连接。

大小（以像素为单位）应在 [1, 16383] 范围内。如果图片的宽度或高度超过所请求的尺寸，则对其进行缩放和剪裁（保持宽高比）。

示例：

base-url=wmax-width-hmax-height-c

在此示例中，应用显示的媒体内容是 正好 256 像素宽，256 像素高，例如 缩略图：

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

说明

下载参数 d。

如果您想下载保留所有 Exif 元数据的图片 （位置元数据除外），请将基准网址与 d 参数。

示例：

base-url=d

在此示例中，应用下载包含全部 （位置元数据除外）：

https://lh3.googleusercontent.com/p/Az....XabC=d

视频基准网址

以下是您可以对视频基准网址使用的选项列表：

参数
dv

说明

如需访问视频 mediaItem 的字节，请串联 包含下载视频“dv”的“baseUrl” 参数。

dv 参数请求的是高品质 原始视频的转码版本。参数不是 与 w 和 h 兼容 参数。

视频下载基准网址最多可能需要几秒钟的时间才能 返回字节数。

在使用此参数之前，请检查媒体内容项的 mediaMetadata.status 字段是否为 READY。 否则，如果您的媒体内容尚未处理完毕，您可能会收到错误消息。

示例：

base-url=dv

以下示例展示了如何下载视频的字节：

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w、h、c和 d

说明

如需访问视频的缩略图，请使用任意图片基准网址参数。

默认情况下，所有视频缩略图都会叠加播放某次视频 按钮。要删除此叠加层，请参阅 -no 参数。

示例：

请参阅映像基准网址表格 获取示例。
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

说明

如需检索动态照片媒体项的视频元素，请使用 dv 参数，就像您从视频基准网址下载一样。
w、h、c和 d

说明

如需检索动态照片媒体内容的照片元素，请使用图片基准网址的格式。