גישה לפריטי מדיה שנוצרו על ידי אפליקציה

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

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

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

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

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

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

אם פריט המדיה הוא סרטון, קודם צריך לעבד את קובץ הסרטון. השדה 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"
  }
}

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

כדי לאחזר כמה פריטי מדיה לפי המזהים שלהם, צריך להפעיל את 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."
      }
    }
  ]
}

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

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

ב-Picker API:

כל האובייקטים מסוג PickedMediaItem.mediaFile כוללים baseUrl.

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

ב-Library API:

כתובות ה-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 הבסיסיות להורדות סרטונים יחזירו בייטים.

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