列出媒体库内容、影集和媒体内容

必需的授权范围

Google Photos Library API 包含多个用于访问媒体内容和影集的范围。 从各种调用返回的媒体内容会因范围而异 已由开发者提出请求

photoslibrary.readonly 范围允许访问 用户的内容库。photoslibrary.readonly.appcreateddata 范围允许访问 仅应用于应用创建的媒体内容。如需了解详情,请参阅 授权范围

概览

该 API 的一个重要用途是列出用户已备份的媒体内容 Google 相册。特定影集或用户整个页面中的内容 (Google 相册应用中的默认视图)。

您可以使用滤镜选择照片 与指定日期、内容类别或媒体类型匹配的项目时, 用户的内容库。当你列出来自以下来源的项时,不支持此功能 影集。

列出媒体库和影集内容会返回媒体内容列表。 属于影集的扩充项 未包含在内。媒体内容用于描述照片、视频或其他媒体内容。答 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"
}

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

每个返回的影集都有一个 ID,可用于检索 相册,如列出影集内容中所述。它还 包括标题和其中包含的媒体项数量。

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

coverPhotoMediaItemId 包含媒体内容 ID 代表此相册的封面照片。如需访问此封面图片,请使用 coverPhotoBaseUrl。如果没有指定,则不应直接使用 coverPhotoBaseUrl 指定额外 参数

在用户账号中创建或添加到用户 并且您的应用已共享其他 shareInfo 资源。 有关详情,请参阅分享媒体内容

影集还可能包含一个 isWriteable 标记,用于指明您能否创建媒体内容 相册中有 项。如果未返回该标记,则其默认为 false。时间是 取决于向您的应用授予的访问权限,包括:

  • 影集的创建者。
  • 是否共享。
  • 用户的范围 已批准。

如果其中任何条件发生变化,该标志都可能会发生变化。有关详情,请参阅 创建影集。通过 响应还包含一个 nextPageToken。如需了解详情,请参阅 分页

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

列出库内容

您可以列出用户 Google 相册媒体库中的所有媒体内容。 其中不包括已归档和已删除的内容。您可以根据媒体项的顺序列出媒体项, 通过应用 过滤器。如果用户尚未添加 可在 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"
}

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

响应包含媒体内容列表,按时间由近到远排序。 如需了解详情,请参阅 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"
}

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

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

列出共享影集

您可以检索用户已分享或已被用户分享的所有影集的列表 与用户共享。这类似于“分享”标签 Google 相册应用。

用户添加到其 Google 相册媒体库中的共享影集 列出影集调用中也会返回这些影集。确保 以下调用通过 Library API 列出共享影集:

REST

以下是请求示例:

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

该请求会返回以下结果:

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

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

sharedAlbums 中包含影集列表。如需了解详情,请参阅 列出影集。该响应还包含一个 nextPageToken。 如需了解详情,请参阅分页

您的应用创建和共享的影集还会包含额外的 shareInfo。 属性。有关详情,请参阅共享 媒体

列出应用创建的影集

您可以使用 在以下调用中将 excludeNonAppCreatedData 设置为 true

REST

以下是一个 GET 请求,用于列出用户 仅由您的应用创建的 Google 相册媒体库:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

这是一个 GET 请求,可列出用户 仅由您的应用创建的 Google 相册媒体库:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST 的分页

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

对于 mediaItems:searchmediaItems:list 调用,默认页面大小为 25 项内容。我们建议您使用此页面大小,因为它能在 响应大小和填充率媒体项的页面大小上限 search 和 list 请求的形式为 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 不应在同一 请求。