访问应用创建的媒体内容

通过调用列出照片库或影集内容后，您的应用应存储媒体内容的 ID，而非返回的媒体内容本身。这是因为媒体内容可能会发生变化，并且响应中包含的网址会在一段时间后过期。媒体内容 ID 是媒体内容（例如用户媒体库内的照片或视频）的唯一标识。

注意 ：您的应用不应长时间缓存用户的照片或视频。根据您的用例，您可以根据需要存储或缓存媒体内容 ID。对用户数据的访问受隐私权义务的约束。

所需的授权范围

如需访问应用创建的媒体内容，需要 photoslibrary.readonly.appcreateddata 范围。如需详细了解范围，请参阅授权范围。

媒体项

mediaItem 表示已上传到 Google 相册媒体库的媒体内容（例如照片或视频），属于顶层对象，且其属性会因底层媒体类型而有所不同。

下表列出了 mediaItem 属性：

属性
id	用于标识对象的永久性固定 ID。
description	Google 相册中显示的媒体内容说明。
baseUrl	用于访问原始字节。如需了解详情，请参阅基准网址。
productUrl	指向 Google 相册内图片的链接。此链接开发者无法打开，只能由用户打开。网址指向媒体库中的媒体内容。如果网址是从影集搜索中检索到的，则指向影集中的项。
mimeType	媒体内容的类型，有助于轻松识别媒体类型（例如：image/jpg）。
filename	Google 相册应用中向用户显示的媒体内容文件名（位于内容的信息部分）。
mediaMetadata	因媒体的底层类型而异，例如 photo 或 video。 为减少载荷，可以使用字段掩码。

获取媒体内容

如需检索媒体内容，请使用 mediaItemId 调用 mediaItems.get。请求将返回单项媒体内容。

mediaItem 包含各项属性，例如 ID、说明和网址。photo 或 video 中的其他信息基于文件内的元数据。并非所有属性均存在。

如果媒体内容是视频，则必须先处理视频文件。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"
  }
}

获取多项媒体内容

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

基本网址

Google 相册 API 中的基准网址可让您访问媒体内容的原始字节，从而让您的应用能够下载或显示这些内容。在列出影集 (Library API) 或访问媒体内容（Library 和 Picker API）时，这些网址会包含在响应中。请注意，基本网址需要额外的参数才能正常运行。

对于 Picker API：

所有 PickedMediaItem.mediaFile 对象都包含 baseUrl。

基本网址会在 60 分钟内保持有效状态，但如果用户通过其 Google 账号设置撤消了应用的权限，则可能会提前过期。

注意 ：对 PickedMediaItem.mediaFile baseUrl 的请求必须包含包含有效 OAuth 2.0 不记名令牌的 Authorization 标头。

对于 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 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 像素和 720 像素，且不包含播放按钮叠加层： https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

动态照片基准网址

动态照片同时包含照片和视频元素。您可以使用图片基准网址或视频基准网址中的参数来发出动态照片 baseUrl 请求。

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