您正在查看 Google Photos Library API 的旧版文档。

此页面由 Cloud Translation API 翻译。

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

必需的授权范围

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。如需了解详情，请参阅分页。

空影集的响应各不相同，mediaItemsCount 和 coverPhotoMediaItemId 默认设置为 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:search 和 mediaItems: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 不应在同一请求。