访问媒体内容

通过调用列出照片库或影集内容后，您的应用应存储媒体内容的 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 范围时，系统才会填充此字段。

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

获取媒体内容

如需检索媒体内容，请使用 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

说明

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

如需访问图片媒体内容（例如照片或视频缩略图），您必须指定计划在应用中显示的尺寸（以便在保留宽高比的同时将图片调整到相应尺寸）。为此，请将基准网址与所需的尺寸进行连接，如示例所示。

示例：

base-url=wmax-width-hmax-height

以下示例显示宽度不超过 2048 px 且高度不超过 1024 px 的媒体内容：

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

说明

剪裁参数 c。

如果要将图片剪裁为您指定的确切宽度和高度，请将基准网址与可选的 -c 参数以及必需的 w 和 h 参数连接起来。

大小（以像素为单位）应在 [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

说明

下载参数 d。

如要下载保留除位置元数据之外所有 Exif 元数据的图片，请将基准网址与 d 参数进行连接。

示例：

base-url=d

在此示例中，应用会下载一张图片，其中包含除位置元数据之外的所有元数据：

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

视频基准网址

以下是可与视频基准网址一起使用的参数选项列表：

参数
dv

说明

如需访问视频 mediaItem 的字节，请将 baseUrl 与下载视频 dv 参数进行串联。

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

说明

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