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

אחרי שמשתמש בוחר פריטים של מדיה באמצעות 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) או ניגשים לפריטי מדיה (גם 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

תיאור

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

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