مدیریت آلبوم‌ها

در Google Photos، می‌توانید عکس‌ها و دیگر فایل‌های رسانه‌ای را بااستفاده از آلبوم‌ها سازمان‌دهی کنید. یک فایل رسانه‌ای می‌تواند با یک یا چند آلبوم مرتبط باشد. برای شروع مرتبط کردن فایل‌های رسانه‌ای با آلبوم، ابتدا باید آلبوم را ایجاد کنید.

گستره‌های مجوز لازم

برای ایجاد آلبوم، برنامه‌تان باید حداقل یکی از گستره‌های مجوز زیر را درخواست کند:

  • photoslibrary.appendonly
  • photoslibrary.sharing

برای تغییر دادن عنوان یا عکس جلد آلبوم‌ها پس‌از ایجاد آن‌ها، از گستره photoslibrary.edit.appcreateddata استفاده کنید.

درحال ایجاد آلبوم جدید

برای ایجاد آلبوم، albums.create را فراخوانی کنید و title را اضافه کنید. توجه داشته باشید که title به ۵۰۰ نویسه محدود شده است.

تماس آلبومی را برمی‌گرداند. برنامه شما می‌تواند شناسه آلبوم را از این اطلاعات ذخیره کند و از آن برای بارگذاری فایل‌های رسانه‌ای در آلبوم خاص استفاده کند.

استراحت

در اینجا سرایندی برای درخواست پست (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"
}

جاوا

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.appcreateddata مجوز استفاده کنید.

طول عنوان آلبوم نباید بیشتر از ۵۰۰ نویسه باشد. فایل‌های رسانه‌ای جلد باید متعلق به مالک آلبوم باشند و به آلبومی تعلق داشته باشند که قرار است جلد آن باشند.

استراحت

در اینجا سرایند درخواست 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"
}

جاوا

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 Photos کاربر به آلبوم اضافه کنید. فایل‌های رسانه‌ای به ترتیبی که در این تماس ارائه شده است به انتهای آلبوم اضافه می‌شوند.

اگر فایل رسانه‌ای یا آلبوم نامعتبری مشخص شده باشد، کل درخواست ناموفق خواهد بود. موفقیت جزئی پشتیبانی نمی‌شود.

هر آلبوم می‌تواند حداکثر ۲۰٬۰۰۰ فایل رسانه‌ای داشته باشد. درخواست‌های افزودن موارد بیشتر که از این حد فراتر برود ناموفق خواهد بود.

توجه داشته باشید که فقط می‌توانید فایل‌های رسانه‌ای را اضافه کنید که توسط برنامه شما به آلبوم‌هایی که برنامه شما ایجاد کرده است بارگذاری شده‌اند. فایل‌های رسانه‌ای باید در کتابخانه کاربر نیز باشد. برای آلبوم‌هایی که هم‌رسانی شده‌اند، یا باید متعلق به کاربر باشند یا کاربر باید مشارکت‌کننده‌ای باشد که قبلاً به آلبوم پیوسته است.

برای افزودن فایل‌های رسانه‌ای به آلبوم، albums.batchAddMediaItems را با شناسه‌های فایل‌های رسانه‌ای و آلبوم فراخوانی کنید.

استراحت

در اینجا سرایندی برای درخواست پست (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 را برمی‌گرداند.

جاوا

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 را با شناسه‌های فایل‌های رسانه‌ای و آلبوم فراخوانی کنید.

استراحت

در اینجا سرایندی برای درخواست پست (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 را برمی‌گرداند.

جاوا

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
}