列出应用创建的媒体内容和影集

所需的授权范围

展示应用创建的内容需要 photoslibrary.readonly.appcreateddata 范围。有关范围的详情，请参阅授权 范围。

概览

利用 Library API，您可以列出和访问应用 已创建。

列出媒体项的一些主要功能包括：

列出媒体库和影集内容会返回媒体内容列表。 但不包括同属于影集的丰富内容。媒体内容用于描述照片、视频或其他媒体内容。答 mediaItem包含指向相应内容的直接链接，以及指向此内容的链接 Google 相册和其他相关元数据。如需了解详情，请参阅 访问媒体内容和 mediaItems。

列出应用创建的影集

您可以使用 albums.list。

REST

以下是请求示例：

GET https://photoslibrary.googleapis.com/v1/albums

该请求会返回以下结果：

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

每个返回的影集都有一个 ID，可用于获取列出影集内容中显示的影集内容。此外，每个影集都带有标题以及所含的媒体内容数量。

productUrl 指向 Google 相册中可用作影集的影集， 。

coverPhotoMediaItemId 包含媒体内容 代表封面/封底的 ID 此影集的照片。如需访问此封面图片，请使用 coverPhotoBaseUrl。 在未指定参数的情况下，请勿直接使用 coverPhotoBaseUrl。 其他参数。

该响应还包含一个 nextPageToken。如需了解详情，请参阅分页。

空影集的响应各不相同，mediaItemsCount 和 coverPhotoMediaItemId 默认设置为 0，并且 REST 中会将其省略 响应。另请注意，coverPhotoBaseUrl 指向默认占位符 图片。

列出应用创建的媒体库内容

您可以列出用户 Google 相册媒体库中的所有媒体内容 由您的应用创建的其中不包含已归档和已删除的内容。您 您可以根据内容、日期和其他属性列出媒体内容，方法是 应用过滤条件。

要列出媒体项，请调用 mediaItems.list。

REST

以下是请求示例：

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

GET 请求将返回以下响应：

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

响应包含媒体内容列表，按时间由近到远排序。 如需了解详情，请参阅 mediaItems。它还 包含 nextPageToken，有关此内容的详细介绍，请参阅 分页。

列出影集内容

要列出影集中的所有媒体内容，请将 albumId 字段添加到您的 搜索请求。如需详细了解 albumId，请参阅商品详情 影集。如果 albumId 无效，则会返回 Bad Request 错误 返回。ID 有效，但经过身份验证的影集不存在 系统会返回 Not Found 错误。如需详细了解错误处理，请参阅性能提示和最佳做法。

REST

以下是请求示例：

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

POST 请求会返回以下响应：

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

响应包含一个 nextPageToken 和媒体内容列表。取消 列出媒体库内容，媒体项将按照其在 影集。有关详情，请参阅 mediaItems和 分页。用户可以在 Google 相册界面。

设置 albumId 后，您在列出影集内容时就无法应用过滤条件。 这样做会导致 Bad Request 错误。

REST 的分页

为了提高性能，返回大量结果的方法（如 list 方法）对响应进行分页。每个类别中的结果数量上限 页面由 pageSize 参数指定。

对于 mediaItems.search 和 mediaItems.list 调用，默认页面大小为 25 项。我们建议您使用此页面大小，因为它能在 响应大小和填充率媒体内容搜索和列表请求的最大页面大小为 100 项。

列出影集时，默认和建议的页面大小为 20 个影集，每个影集的 最多 50 个影集。

当可用结果数超过页面大小时，响应 包含一个 nextPageToken，它向您的应用表明 更多结果。

示例

您必须将 nextPageToken 附加到参数中的后续请求 pageToken，如以下示例所示。同时指定 pageToken 与操作所需的其他参数一起传递，可以放在 请求或作为查询参数。

请求 #1

{
  "pageSize": "5",
  "filters": { … }
}

响应 #1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

请求 #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

响应 #2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

一直持续此模式，直到不再有 nextPageToken 对象为止。

nextPageToken 仅对同一请求有效。如果任何参数 不同，之前用过的 nextPageToken 不应在同一 请求。