管理影集

在 Google 相册中,您可以使用影集整理照片和其他媒体内容。 媒体内容可与一个或多个影集相关联。如需开始将媒体内容与影集相关联,您需要先创建影集。

必需的授权范围

如需创建影集,您的应用必须至少请求以下一项授权范围

  • photoslibrary.appendonly
  • photoslibrary.sharing

如需在创建影集后更改影集的标题或封面照片,请使用 photoslibrary.edit.appcreateddata 范围。

创建新影集

如需创建影集,请调用 albums.create 并添加 title。请注意,title 的长度上限为 500 个字符。

调用会返回一个影集。您的应用可以存储此信息中的影集 ID,并使用此 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

以下是用于更新专辑的 titlecoverPhotomediaItemId 的 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
}