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

אחרי ביצוע שיחות אל להציג את התוכן של ספריית התמונות או האלבום, במקום לאחסן את פריטי המדיה שהוחזרו, האפליקציה צריכה לאחסן את המזהים של פריטי המדיה. הסיבה לכך היא שהתוכן של פריטי המדיה עשוי ואחרי פרק זמן מסוים, התוקף של כתובות ה-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 שמתאר את במצב העיבוד של קובץ הסרטון. קובץ חדש שהועלה יחזיר את videoProcessingStatus עם הערך PROCESSING קודם, לפני 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

תיאור

הרוחב, w והגובה, 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 בסיסיות להורדת סרטונים עשויות להימשך כמה שניות מחזירה בייטים. כברירת מחדל, הורדות של סרטונים הן באמצעות קידוד H.264. אם הקידוד של H.264 נכשל, המערכת תשתמש ב-VP9.

לפני שמשתמשים בפרמטר הזה, צריך לוודא שפריטי המדיה השדה 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

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

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

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

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

פרמטר
dv

תיאור

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

תיאור

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