在 Google 相册中,您可以使用影集整理照片和其他媒体内容。 媒体内容可与一个或多个影集关联。如需开始将媒体内容与影集相关联,您需要先创建影集。
必需的授权范围
如需创建影集,您的应用必须至少请求以下一项授权范围:
photoslibrary.appendonly
photoslibrary.sharing
如需在创建影集后更改其标题或封面照片,请使用 photoslibrary.edit.appcreateddata
范围。
创建新影集
如需创建影集,请调用 albums.create
并添加 title
。请注意,title
不得超过 500 个字符。
此调用会返回一个影集。您的应用可以存储此信息中的影集 ID,并用其向特定影集上传媒体内容。
REST
以下是 POST 请求的标头:
POST https://photoslibrary.googleapis.com/v1/albums Content-type: application/json Authorization: Bearer oauth2-token
请求正文如下所示:
{ "album": { "title": "new-album-title" } }
如果请求成功,响应将返回一个影集:
{ "productUrl": "album-product-url", "id": "album-id", "title": "album-title", "isWriteable": "whether-you-can-write-to-this-album" }
Java
try { Album createdAlbum = photosLibraryClient.createAlbum("My Album"); // The createdAlbum object contains properties of an album String productUrl = createdAlbum.getProductUrl(); // coverPhotoBaseUrl shouldn't be used as is. Append parameters to base URLs before use String albumCoverImage = createdAlbum.getCoverPhotoBaseUrl() + "=w2048-h1024"; boolean isWriteable = createdAlbum.getIsWriteable(); } catch (ApiException e) { // Handle error }
PHP
try { $newAlbum = PhotosLibraryResourceFactory::album("My Album"); $createdAlbum = $photosLibraryClient->createAlbum($newAlbum); // The createdAlbum object contains properties of an album $albumId = $createdAlbum->getId(); $productUrl = $createdAlbum->getProductUrl(); // coverPhotoBaseUrl shouldn't be used as is. Append parameters to base URLs before use $albumCoverImage = $createdAlbum->getCoverPhotoBaseUrl() . '=w2048-h1024'; $isWriteable = $createdAlbum->getIsWriteable(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
更改影集标题和封面照片
如需更改影集标题或封面照片,请创建一个包含影集标识符的 album update
call
,并在请求中包含新标题或新封面照片的媒体内容 ID。您需要使用 photoslibrary.edit.appcreateddata
授权范围才能进行更改。
影集标题的长度不得超过 500 个字符。封面媒体内容必须归影集所有者所有,并且属于影集将用作封面的影集。
REST
以下是用于更新影集的 title
和 coverPhotomediaItemId
的 PATCH 请求标头。
PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId
此请求通过添加字段掩码(由网址中的 updateMask
参数表示)来确定要更新的属性。需要为每个要更新的影集属性传递 updateMask
参数。
对于要更新的每个属性,请在请求正文中包含其详细信息:
{ "title": "new-album-title", "coverPhotoMediaItemId": "new-cover-media-item-id" }
如果成功,响应将返回更新后的 album
详细信息:
{ "id": "album-id", "title": "new-album-title", "productUrl": "album-product-url", "isWriteable": "true-if-user-can-write-to-this-album", "mediaItemsCount": "number-of-media-items-in-album", "coverPhotoBaseUrl": "cover-photo-base-url_use-only-with-parameters", "coverPhotoMediaItemId": "new-cover-media-item-id" }
Java
try { // Update the cover photo of the album given a MediaItem object. Album updatedAlbum = photosLibraryClient.updateAlbumCoverPhoto(album, newCoverMediaItem); // Alternatively, you can update the cover photo of the album given a media item ID. // The specified media item identifier must be not null or empty. // Album updatedAlbum = photosLibraryClient.updateAlbumCoverPhoto(album, "new-cover-media-item-id"); } catch (ApiException e) { // Handle error } try { // Update the title of the album. // The new title must not be null or empty. Album updatedAlbum = photosLibraryClient.updateAlbumTitle(album, "new-album-title"); } catch (ApiException e) { // Handle error }
PHP
try { // ID of the album to update. $albumId = "ALBUM_ID"; // Media item ID of the new cover photo. // Must not be null or empty. $newCoverMediaItemId = "new-cover-media-item-id"; // Update the cover photo of the album. $mediaItem = $photosLibraryClient->updateAlbumCoverPhoto($albumId, $newCoverMediaItemId); } catch (\Google\ApiCore\ApiException $e) { // Handle error } try { // ID of the album to update. $albumId = "ALBUM_ID"; // New title of the album. // Must not be null or empty. $newTitle = "new-album-title"; // Update the title of the album. $mediaItem = $photosLibraryClient->updateAlbumTitle($albumId, $newTitle); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
将媒体内容添加到影集
您可以通过调用 albums.batchAddMediaItems
将用户 Google 相册媒体库中的媒体内容添加到影集。媒体内容将按照此调用中指定的顺序添加到影集末尾。
如果指定了无效的媒体内容或影集,整个请求都会失败。 不支持部分成功。
每个影集最多可包含 20,000 项媒体内容。如果请求添加更多超出此限制的内容,请求将会失败。
请注意,您只能将应用上传的媒体内容添加到应用创建的影集。媒体内容还必须位于用户的媒体库中。对于共享影集,其必须归用户所有,或者用户必须是已加入该影集的协作者。
如需将媒体内容添加到影集,请使用媒体内容和影集的标识符调用 albums.batchAddMediaItems
。
REST
以下是 POST 请求的标头:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchAddMediaItems Content-type: application/json Authorization: Bearer oauth2-token
请求正文如下所示:
{ "mediaItemIds": [ "media-item-id", "another-media-item-id", ... ] }
如果成功,该响应将返回空的 JSON 响应和 HTTP 成功状态。
Java
try { // List of media item IDs to add List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID"); // ID of the album to add media items to String albumId = "ALBUM_ID"; // Add all given media items to the album photosLibraryClient.batchAddMediaItemsToAlbum(albumId, mediaItemIds); } catch (ApiException e) { // An exception is thrown if the media items could not be added }
PHP
try { // List of media item IDs to add $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID"]; // ID of the album to add media items to $albumId = "ALBUM_ID"; // Add all given media items to the album $response = $photosLibraryClient->batchAddMediaItemsToAlbum($albumId, $mediaItemIds); } catch (\Google\ApiCore\ApiException $e) { // Handle Error }
从影集中移除媒体内容
您可以通过调用 albums.batchRemoveMediaItems
从影集中移除已添加的媒体内容。
如果指定了无效的媒体内容,整个请求将会失败。不支持部分成功。
请注意,您只能移除应用添加到影集的媒体内容,或作为上传内容在影集中创建的媒体内容。对于共享影集,如果您代表影集的所有者执行操作,则只能移除其他协作者添加的内容。
如需从影集中移除媒体内容,请使用媒体内容和影集的标识符调用 albums.batchRemoveMediaItems
。
REST
以下是 POST 请求的标头:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchRemoveMediaItems Content-type: application/json Authorization: Bearer oauth2-token
请求正文如下所示:
{ "mediaItemIds": [ "media-item-id", "another-media-item-id", ... ] }
如果成功,该响应将返回空的 JSON 响应和 HTTP 成功状态。
Java
try { // List of media item IDs to remove List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID"); // ID of the album to remove media items from String albumId = "ALBUM_ID"; // Remove all given media items from the album photosLibraryClient.batchRemoveMediaItemsFromAlbum(albumId, mediaItemIds); } catch (ApiException e) { // An exception is thrown if the media items could not be removed }
PHP
try { // List of media item IDs to remove $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID"]; // ID of the album to remove media items from $albumId = "ALBUM_ID"; // Remove all given media items from the album $response = $photosLibraryClient->batchRemoveMediaItemsFromAlbum($albumId, $mediaItemIds); } catch (\Google\ApiCore\ApiException $e) { // Handle Error }