在 Google 相簿中,你可以使用相簿整理相片和其他媒體項目。 一個媒體項目可以與一或多本相簿建立關聯。如要開始將媒體項目與相簿建立關聯,請先建立相簿。
必要的授權範圍
如要建立專輯,應用程式必須至少要求下列其中一個授權範圍:
photoslibrary.appendonly
photoslibrary.sharing
如要在建立後變更相簿的標題或封面相片,請使用 photoslibrary.edit.appcreateddata
範圍。
建立新相簿
如要建立相簿,請呼叫 albums.create
並加入 title
。請注意,title
的長度上限為 500 個字元。
此呼叫會傳回 Album。您的應用程式可以儲存這項資訊中的相簿 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 }
變更相簿標題和封面相片
如要變更相簿標題或封面相片,請使用相簿的 ID 建立 album update
call
,並在要求中加入新標題或新封面相片的媒體項目 ID。您必須使用 photoslibrary.edit.appcreateddata
授權範圍進行變更。
相簿標題長度不得超過 500 個字元。封面媒體項目須為相簿擁有者擁有,且屬於該相簿的擁有者。
REST
以下是 PATCH 要求標頭,用於更新相簿的 title
和 coverPhotomediaItemId
。
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 個媒體項目。新增更多項目若超出這項限制,要求就會失敗。
請注意,您只能將應用程式上傳的媒體項目新增至應用程式建立的相簿。媒體項目也必須位於使用者的媒體庫中。共享相簿必須是使用者擁有,或使用者必須是已加入相簿的協作者。
如要將媒體項目新增至相簿,請使用媒體項目和相簿的 ID 呼叫 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
來移除已新增到相簿的媒體項目。
如果指定無效的媒體項目,整個要求都會失敗。系統不支援部分成功。
請注意,您只能移除應用程式已加入專輯的媒體項目,或是在上傳過程中在相簿中建立的媒體項目。對於共享相簿,只有由您代表相簿的擁有者操作時,您才能移除其他協作者新增的項目。
如要從相簿中移除媒體項目,請使用媒體項目和相簿的 ID 呼叫 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 }