列出和检索媒体项

用户在 Google 相册中配置氛围模式设备并选择媒体来源后，您的应用就可以列出和检索要显示的这些媒体内容。

前期准备

• 检查设备设置：确保您已成功为用户创建和配置设备。
• 了解 Ambient API 流程：查看 Ambient API 流程，了解整个流程，尤其是涉及轮询 mediaSourcesSet 的步骤。

mediaSourcesSet 的投票

您必须先列出设备的媒体内容，然后用户才能在 Google 相册应用中选择要与您的应用分享的照片。您的应用必须轮询设备，以确定何时进行此选择。

定期调用特定 deviceId 的 devices.get 方法。监控 AmbientDevice 响应中的 mediaSourcesSet 字段。它最初为 false。用户成功选择媒体来源后，此字段将更改为 true。

AmbientDevice 响应包含一个包含 pollInterval 的 pollingConfig，您应将其用作轮询频率的准则。

列出媒体项

当设备的 mediaSourcesSet 为 true 后，您就可以开始提取用户选择的媒体内容。

1. 使用 mediaItems.list 端点：向 https://photosambient.googleapis.com/v1/mediaItems 发出 GET 请求，并在路径中提供 deviceId。

2. 处理分页（如有必要）：响应可能会分页。使用 pageSize 参数指定要返回的项数上限，并使用上一个响应中的 pageToken 检索后续页面的结果。

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

   • id：媒体内容的唯一标识符。
   • creationTime：媒体内容创建时的时间戳。
   • mediaFile：包含用于访问实际内容的详细信息的对象。

mediaFile 字段包含 baseUrl。您将使用此 baseUrl 构建网址，以便以各种分辨率或格式访问媒体内容。

基本网址

Google 相册 API 中的基准网址可让您访问媒体内容的原始字节，从而让您的应用能够下载或显示这些内容。列出影集 (Library API) 或访问媒体内容 (Library API 和 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 像素和 720 像素，且不包含播放按钮叠加层： https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

动态照片基准网址

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

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

后续步骤

• 示例应用：我们的示例应用包含列出和检索媒体内容的示例。如需了解详情，请参阅 checkMediaSourcesSet 和 fetch_media_item_list 函数。
• 参考文档：查看全面的媒体内容参考文档，详细了解所有可用方法、请求和响应参数以及错误代码。