Управление альбомами

В Google Фото можно упорядочивать фотографии и другие мультимедийные объекты с помощью альбомов. Мультимедийный объект может быть связан с одним или несколькими альбомами. Чтобы начать связывать мультимедийные объекты с альбомом, сначала нужно создать альбом.

Необходимые области авторизации

Чтобы создать альбом, приложение должно запросить хотя бы одну из следующих областей авторизации:

  • photoslibrary.appendonly
  • photoslibrary.sharing

Чтобы изменить название или обложку альбома после его создания, используйте область действия photoslibrary.edit.appcreateddata.

Как создать новый альбом

Чтобы создать альбом, вызовите albums.create и укажите title. Обратите внимание, что в поле title можно ввести не более 500 символов.

Вызов возвращает альбом. Приложение может сохранить идентификатор альбома из этой информации и использовать его для загрузки мультимедийных объектов в определенный альбом.

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 с идентификатором альбома и укажите в запросе новое название или идентификатор объекта, который нужно использовать в качестве обложки. Для этого вам понадобится область действия photoslibrary.edit.appcreateddataauthorization.

Название альбома не должно превышать 500 символов. Мультимедийные объекты, используемые в качестве обложки, должны принадлежать владельцу альбома и находиться в альбоме, для которого они будут обложкой.

REST

Ниже приведен пример заголовка запроса PATCH, который обновляет свойства title и coverPhotomediaItemId альбома.

PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId

Этот запрос определяет, какие свойства обновляются, включая маску поля, указанную параметрами updateMask в URL. Параметр 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
}

Добавление мультимедийных объектов в альбом

Вы можете добавить мультимедийные объекты из библиотеки Google Фото пользователя в альбом, вызвав метод albums.batchAddMediaItems. Мультимедийные объекты добавляются в конец альбома в порядке, указанном в этом вызове.

Если указан недопустимый мультимедийный объект или альбом, запрос не будет выполнен. Частичный успех не поддерживается.

В каждом альбоме может быть до 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 Success.

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 Success.

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
}