הצגת רשימה ואחזור של פריטי מדיה

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

לפני שמתחילים

  • הסבר על התהליך: במאמר תחילת העבודה עם Picker API מוסבר על תהליך בחירת התמונות כולו.
  • השלמת הבחירה של פריטי המדיה: מוודאים שהמשתמש הצליח לבחור פריטי מדיה מהסשן שלו. למידע נוסף עיינו במדריך לסשנים.
  • בדיקת היקפי ההרשאה הנדרשים: כדי לעבוד עם סשנים צריך את ההיקף photospicker.mediaitems.readonly. למידע נוסף על היקפים, ראו היקפי הרשאות.

הצגת רשימה של קובצי המדיה שנבחרו

  1. שימוש בנקודת הקצה mediaItems.list: שולחים בקשת GET אל https://photospicker.googleapis.com/v1/mediaItems, ומספקים את sessionId כפרמטר של שאילתה.

  2. חלוקה לדפים (אם צריך):

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

  3. עיבוד פריטי המדיה: התגובה תכיל מערך של PickedMediaItem אובייקטים, שכל אחד מהם מייצג פריט מדיה שנבחר. האובייקטים האלה כוללים פרטים חיוניים כמו:

    • id: המזהה הייחודי של פריט המדיה.
    • baseUrl: כתובת ה-URL הבסיסית שממנה אפשר ליצור כתובות URL כדי לגשת לתוכן של פריט המדיה ברזולוציות שונות.
    • mimeType: סוג ה-MIME של פריט המדיה (למשל, image/jpeg,‏ video/mp4).

אחזור קובצי המדיה שנבחרו

כדי לאשר את הבקשות, חשוב לוודא שיש לכם אסימון גישה תקין מסוג OAuth 2.0 עם ההיקף https://www.googleapis.com/auth/photospicker.mediaitems.readonly.

  • יצירת כתובת ה-URL של התוכן: משתמשים ב-baseUrl מהאובייקט PickedMediaItem. מוסיפים את הרזולוציה או את פורמט הקובץ ל-baseUrl. פרטים נוספים זמינים בקטע בנושא כתובות URL בסיסיות.

  • אחזור התוכן: שולחים בקשת GET לכתובת ה-URL הבסיסית של פריט המדיה. התגובה תכיל את הבייטים של פריט המדיה (תמונה או וידאו). יש כמה אפשרויות שונות של baseURL.

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

כתובות URL בסיסיות ב-Google Photos APIs מספקות גישה לבייטים הגולמיים של פריטי המדיה, ומאפשרות לאפליקציה להוריד או להציג אותם. כתובות ה-URL האלה נכללות בתגובות כשמציגים אלבומים (ב-Library API) או כשניגשים לפריטי מדיה (בממשקי ה-API של הספרייה וגם בממשקי ה-API של Picker). חשוב לזכור שכתובות 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 של בסיס תמונות.