访问媒体内容

调用 列出某个照片库或影集的内容 而不是存储返回的媒体项，而是应存储 媒体项的 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

仅当媒体内容位于共享影集中时，系统才会填充此字段 并且用户已授予 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
}

获取多项媒体内容

要按标识符检索多个媒体项，请调用 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

说明

宽度 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 兼容 参数。

视频下载基准网址最多可能需要几秒钟的时间才能 返回字节数。视频下载内容默认采用 H.264 编码。如果 H.264 编码失败，将使用 VP9。

在使用此参数之前，请检查媒体内容的 “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

说明

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