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

所需的授权范围

列出应用创建的内容需要 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 的分页

为了提高性能，返回大量结果的方法（例如列表方法）可以对响应进行分页。每页中的最大结果数由 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。