此页面由 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 项。我们建议您使用此页面大小，因为它能在响应大小和填充率之间取得平衡。媒体项搜索和列表请求的页面大小上限为 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。