ניהול אלבומים

ב-Google Photos אפשר לארגן תמונות ופריטי מדיה אחרים באמצעות אלבומים. אפשר לשייך פריט מדיה לאלבום אחד או יותר. כדי להתחיל לשייך פריטים של מדיה לאלבום, קודם צריך ליצור את האלבום.

היקפי ההרשאה הנדרשים

כדי ליצור אלבומים צריך את ההיקף photoslibrary.appendonly.

כדי לשנות את השם או את תמונת השער של האלבומים אחרי היצירה שלהם צריך את ההיקף 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"
}

אחזור פרטי אלבום

כדי לאחזר את הפרטים של אלבום קיים שנוצר על ידי האפליקציה, צריך להפעיל את השיטה albums.get ולציין את הערך של albumId של האלבום שרוצים לאחזר.

הקריאה מחזירה אלבום.

REST

הנה כותרת לבקשת GET:

GET https://photoslibrary.googleapis.com/v1/albums/{albumId}
Content-type: application/json
Authorization: Bearer oauth2-token

גוף הבקשה נראה כך:

{
  "albumId": album-id
}

אם הפעולה בוצעה ללא שגיאות, התשובה תחזיר אלבום:

{
  "id": album-id,
  "title": album-title,
  "productUrl": album-product-url,
  "mediaItemsCount": media-items-count,
  "coverPhotoBaseUrl": cover-photo-base-url,
  "coverPhotoMediaItemId": cover-photo-media-item-id
}

שינוי השמות ותמונות השער של האלבום

כדי לשנות את שם האלבום או את תמונת השער שלו, יוצרים בקשה מסוג album update call עם המזהה של האלבום, ומצרפים לבקשה את השם החדש או את מזהה פריט המדיה של תמונת השער החדשה. כדי לבצע את השינוי, צריך להשתמש בהיקף photoslibrary.edit.appcreateddata authorization.

שמות האלבומים יכולים להיות באורך של עד 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"
}

הוספת קובצי מדיה לאלבום

כדי להוסיף פריטים של מדיה שנוצרו על ידי האפליקציה שלכם לאלבומים שנוצרו על ידה, תוכלו להפעיל את השיטה 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.

איך מסירים פריטים מאלבום

אפשר להסיר פריטים של מדיה שנוצרו על ידי האפליקציה לאלבומים שנוצרו על ידה, על ידי קריאה ל-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
}