必需的授权范围
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
。