必需的授权范围
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
不应在同一
请求。