列出和检索媒体项

用户使用 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 和 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 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	说明 如需检索动态照片媒体内容的照片元素，请使用图片基准网址的格式。