גישה לפריטי מדיה

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

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

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

כדי לגשת לפריטי מדיה, האפליקציה צריכה לבקש לפחות אחד מהיקפי ההרשאה הבאים. הגישה לפריטי המדיה שמוחזרים בתגובה תלויה בהיקפים שביקשת.

  • photoslibrary.readonly מאפשרת גישה לכל פריטי המדיה בספרייה של המשתמש
  • photoslibrary.readonly.appcreateddata מאפשר גישה רק לפריטי מדיה שנוצרו על ידי האפליקציה

פריטים של מדיה

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

בטבלה הבאה מפורטים המאפיינים של mediaItem:

מאפיינים
id מזהה קבוע ויציב המשמש לזיהוי האובייקט.
description תיאור של פריט המדיה כפי שהוא מופיע ב-Google Photos.
baseUrl משמשת לגישה לבייטים הגולמיים. מידע נוסף זמין במאמר כתובות URL בסיסיות.
productUrl

קישור לתמונה ב-Google Photos. המפתח יכול רק לפתוח את הקישור. כתובות ה-URL מפנות לפריט מדיה בספרייה. אם כתובת ה-URL אוחזר מחיפוש אלבום, היא מפנה לפריט באלבום.

mimeType סוג פריט המדיה, כדי לזהות בקלות את סוג המדיה (לדוגמה: image/jpg).
filename שם הקובץ של פריט המדיה שמוצג למשתמש באפליקציית Google Photos (בקטע של פרטי הפריט).
mediaMetadata משתנה בהתאם לסוג הבסיסי של המדיה, למשל photo או video. כדי לצמצם את המטען הייעודי (Payload), אפשר להשתמש במסכות של שדות.
contributorInfo

השדה הזה מאוכלס רק אם פריט המדיה נמצא באלבום משותף שנוצר על ידי האפליקציה הזו, והמשתמש העניק להיקף photoslibrary.sharing.

מכיל מידע על השותף שהוסיף את פריט המדיה הזה. מידע נוסף זמין במאמר שיתוף מדיה.

אחזור פריט מדיה

כדי לאחזר פריט מדיה, קוראים אל mediaItems.get באמצעות mediaItemId. הבקשה מחזירה פריט מדיה אחד.

השדה mediaItem מכיל מאפיינים כמו המזהה, התיאור וכתובת ה-URL. המידע הנוסף ב-photo או ב-video מבוסס על המטא-נתונים שבקובץ. יכול להיות שלא כל המאפיינים יופיעו. השדה ContributorInfo מכיל מטא-נתונים של פריטים שנכללים באלבום משותף. השדה הזה נכלל רק כשמציגים את התוכן של אלבום משותף שהמשתמש העניק לו את היקף ההרשאה photoslibrary.sharing.

אם פריט המדיה הוא סרטון, קודם צריך לעבד את קובץ הסרטון. השדה mediaItem מכיל שדה status בתוך mediaMetadata שמתאר את מצב העיבוד של קובץ הסרטון. קובץ שהועלה לאחרונה מחזיר את הערך PROCESSING ב-videoProcessingStatus קודם, לפני שהוא מוגדר כ-READY לשימוש. הערך baseUrl של פריט מדיה בסרטון יהיה זמין רק אחרי עיבוד הסרטון.

REST

זוהי בקשת GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

התגובה לפריט מדיה של תמונה נראית כך. נכס התמונה מכיל מטא-נתונים של פריטים של תמונות.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

התגובה לפריט מדיה מסוג וידאו נראית כך. נכס הווידאו מכיל מטא-נתונים של פריטים של סרטונים.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Java

נכס התמונה מכיל מטא-נתונים של פריטים של תמונות.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

מאפיין הסרטון מכיל מטא-נתונים של פריטי וידאו.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

מאפיין התמונה מכיל מטא-נתונים של פריטי תמונות.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

נכס הווידאו מכיל מטא-נתונים של פריטים של סרטונים.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

אחזור של כמה פריטים של מדיה

כדי לאחזר כמה פריטי מדיה לפי המזהים שלהם, צריך להפעיל את mediaItems.batchGet באמצעות הערכים של mediaItemId.

הבקשה מחזירה רשימה של MediaItemResults לפי הסדר של מזהי פריטי המדיה שצוינו בבקשה. כל תוצאה מכילה MediaItem או Status אם הייתה שגיאה.

המספר המקסימלי של פריטי מדיה שאפשר לבקש בקריאה אחת הוא 50. הרשימה של פריטי המדיה לא יכולה לכלול מזהים כפולים ולא יכולה להיות ריקה.

REST

זוהי בקשת GET שמציגה גישה מוצלחת ונכשלת לפריטי מדיה. מציינים כל מזהה של פריט מדיה כפרמטר שאילתה חדש של mediaItemIds כחלק מהבקשה:

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

בקשת ה-GET מחזירה את התגובה הבאה:

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

כתובות URL בסיסיות

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

כתובות ה-URL הבסיסיות השונות הן:

  • baseUrl: גישה ישירה לתמונה, לתמונה הממוזערת של סרטון או להורדת ביטים של סרטון.
  • coverPhotoBaseUrl: גישה ישירה לתמונת השער של האלבום.
  • profilePictureBaseUrl: גישה ישירה לתמונת הפרופיל של הבעלים של mediaItem.

כתובות URL בסיסיות של תמונות

זו רשימת האפשרויות שאפשר להשתמש בהן עם כתובות ה-URL הבסיסיות של התמונות:

פרמטר
w, h

תיאור

הפרמטרים width‏ (רוחב), w ו-height‏ (גובה), h.

כדי לגשת לפריט מדיה של תמונה, כמו תמונה או תמונה ממוזערת של סרטון, צריך לציין את המידות שאתם מתכננים להציג באפליקציה (כדי שאפשר יהיה לשנות את קנה המידה של התמונה למידות האלה תוך שמירה על יחס הגובה-רוחב). כדי לעשות זאת, צריך לשרשר את כתובת ה-URL הבסיסית עם המאפיינים הנדרשים, כפי שמתואר בדוגמאות.

לדוגמה:

base-url=wmax-width-hmax-height

דוגמה להצגת פריט מדיה ברוחב של עד 2048 פיקסלים וגובה של עד 1024 פיקסלים:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

תיאור

הפרמטר c של החיתוך.

אם רוצים לחתוך את התמונה לרוחב ולגובה המדויקים שציינתם, צריך לשרשר את כתובת ה-URL הבסיסית עם הפרמטר האופציונלי -c, יחד עם הפרמטרים החובה w ו-h.

הגודל (בפיקסלים) צריך להיות בטווח [1, 16383]. אם הרוחב או הגובה של התמונה חורגים מהגודל המבוקש, התמונה מוקטנת ותחתך (יחס הגובה-רוחב נשמר).

לדוגמה:

base-url=wmax-width-hmax-height-c

בדוגמה הזו, האפליקציה מציגה פריט מדיה בגודל 256 פיקסלים על 256 פיקסלים, למשל תמונה ממוזערת:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

תיאור

הפרמטר d של ההורדה.

אם רוצים להוריד את התמונה שכוללת את כל המטא-נתונים של תצוגת Exif חוץ מהמטא-נתונים של המיקום, צריך משרשרים את כתובת ה-URL הבסיסית עם הפרמטר d.

לדוגמה:

base-url=d

בדוגמה הזו, האפליקציה מורידת תמונה עם כל המטא-נתונים מלבד המטא-נתונים של המיקום:

https://lh3.googleusercontent.com/p/Az....XabC=d

כתובות URL של בסיס סרטונים

זו הרשימה של האפשרויות שאפשר להשתמש בהן עם כתובות ה-URL הבסיסיות של הסרטונים:

פרמטר
dv

תיאור

כדי לגשת לבייטים של סרטון mediaItem, צריך לשרשר את הערך של baseUrl עם הפרמטר dv של הורדת הסרטון.

הפרמטר dv מאפשר לבקש גרסה באיכות גבוהה של הסרטון המקורי שעברה המרת קידוד. הפרמטר לא תואם לפרמטר w ולפרמטר h.

יכול להיות שיחלפו כמה שניות עד שכתובות ה-URL הבסיסיות להורדות סרטונים יחזירו בייטים.

לפני שמשתמשים בפרמטר הזה, צריך לבדוק שהשדה mediaMetadata.status של פריטי המדיה הוא READY. אחרת, אם העיבוד של פריט המדיה לא הסתיים, יכול להיות שתופיע הודעת שגיאה.

לדוגמה:

base-url=dv

בדוגמה הבאה מוסבר איך מורידים את הבייטים של סרטון:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h c וגם d

תיאור

כדי לגשת לתמונה הממוזערת של הסרטון, משתמשים באחד מהפרמטרים של כתובת ה-URL הבסיסית של התמונה.

כברירת מחדל, כל התמונות הממוזערות של הסרטונים כוללות שכבת-על של לחצן הפעלה. כדי להסיר את שכבת-העל הזו, אפשר להיעזר בפרמטר -no.

לדוגמה:

דוגמאות מפורטות בטבלה של כתובות ה-URL הבסיסיות של התמונות.
no

תיאור

הפרמטר no להסרת שכבת-העל של התמונה הממוזערת.

כדי לאחזר את התמונה הממוזערת של סרטון בלי שכבת-העל של לחצן ההפעלה, צריך לשרשר את כתובת ה-URL הבסיסית עם הפרמטר no.

צריך להשתמש בפרמטר no עם לפחות אחד מפרמטרי כתובת ה-URL הבסיסית של התמונה.

לדוגמה:

base-url=wmax-width-hmax-height-no

בדוגמה הבאה מוצגת תמונה ממוזערת של וידאו בגודל 1,280 פיקסלים רוחב על 720 פיקסלים גובה, שלא כוללת שכבת-על של לחצן הפעלה:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

כתובות URL בסיסיות של תמונות עם תנועה

תמונות עם תנועה מכילות גם רכיבי תמונה וגם רכיבי וידאו. אפשר להשתמש בפרמטרים מכתובות URL של בסיס תמונות או מכתובות URL של בסיס סרטונים בבקשות baseUrl של תמונות עם תנועה.

פרמטר
dv

תיאור

כדי לאחזר את רכיב הווידאו של פריט מדיה מסוג 'תמונה בתנועה', משתמשים בפרמטר dv כמו שמשתמשים בו כדי להוריד מכתובות URL בסיסיות של סרטונים.
w, h, c וגם d

תיאור

כדי לאחזר את אלמנט התמונה של פריט מדיה של תמונת תנועה, צריך להשתמש בפורמט של כתובות URL בסיסיות של תמונות.