إدارة الألبومات

في "صور Google"، يمكنك تنظيم الصور وملفات الوسائط الأخرى باستخدام الألبومات. يمكن ربط عنصر وسائط بألبوم واحد أو أكثر. لبدء ربط عناصر الوسائط بألبوم، تحتاج إلى إنشاء الألبوم أولاً.

نطاقات التفويض المطلوبة

لإنشاء ألبوم، يجب أن يطلب تطبيقك واحدًا على الأقل من نطاقات التفويض التالية:

• photoslibrary.appendonly
• photoslibrary.sharing

لتغيير عنوان الألبومات أو صورة غلافها بعد إنشائها، استخدِم نطاق photoslibrary.edit.appcreateddata.

إنشاء ألبوم جديد

لإنشاء ألبوم، يمكنك الاتصال بالرمز albums.create وتضمين title. تجدر الإشارة إلى أنّ title يمكن أن يتضمّن 500 حرف كحد أقصى.

تعرض المكالمة ألبومًا. يمكن لتطبيقك تخزين معرّف الألبوم من هذه المعلومات واستخدامه لتحميل عناصر الوسائط إلى الألبوم المحدد.

راحة

في ما يلي عنوان طلب 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.appcreateddata التفويض لإجراء التغيير.

يجب ألا يزيد طول عناوين الألبومات عن 500 حرف. يجب أن تكون عناصر وسائط الغلاف ملكًا لمالك الألبوم وأن تنتمي إلى الألبوم الذي ستكون غلافه.

راحة

إليك عنوان طلب 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 مع معرّفات عناصر الوسائط والألبوم.

راحة

في ما يلي عنوان طلب 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 مع معرّفات عناصر الوسائط والألبوم.

راحة

في ما يلي عنوان طلب 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
}