本頁面由 Cloud Translation API 翻譯而成。

管理相簿

在 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
}