列出和检索媒体项

用户使用 Picker API 选择媒体内容后，您就可以检索与这些内容相关的信息并访问其内容。本指南概述了列出和检索媒体内容的过程。

前期准备

  • 了解流程：请参阅开始使用 Picker API，简要了解整个照片选择流程。
  • 完成媒体内容选择：确保用户已成功从其会话中选择媒体内容。如需了解详情，请参阅有关会话的指南。
  • 查看所需的授权范围：如需使用会话，您需要拥有 photospicker.mediaitems.readonly 范围。如需详细了解范围，请参阅授权范围。

列出所选媒体内容

  1. 使用 mediaItems.list 端点：向 https://photospicker.googleapis.com/v1/mediaItems 发出 GET 请求，并将 sessionId 作为查询参数提供。

  2. 处理分页（如有必要）：

    如果用户选择大量项，响应可能会分页。使用响应中的 nextPageToken 检索后续页面的结果。

  3. 处理媒体内容：响应将包含一组 PickedMediaItem 对象，每个对象代表一项所选媒体内容。这些对象包含以下基本详细信息：

    • id：媒体内容的唯一标识符。
    • baseUrl：您可以使用此基准网址构建网址，以便以各种分辨率访问媒体内容。
    • mimeType：媒体内容的 MIME 类型（例如 image/jpeg、video/mp4）。

检索所选的媒体内容

确保您拥有有效的 OAuth 2.0 访问令牌（具有 https://www.googleapis.com/auth/photospicker.mediaitems.readonly 范围），以便为请求授权。

  • 构建内容网址：使用 PickedMediaItem 对象中的 baseUrl。将分辨率或文件格式附加到 baseUrl。如需了解详情，请参阅基准网址部分。

  • 提取内容：向媒体内容的基础网址发出 GET 请求。响应将包含媒体内容（图片或视频）的字节。有许多不同的 base网址 选项可供选择。

基本网址

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

对于 Picker API：

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

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

对于 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 像素和 720 像素，且不包含播放按钮叠加层：

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

动态照片基准网址

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

参数
dv

说明

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

说明

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