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

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

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

  • בודקים את הגדרת המכשיר: מוודאים שיצרתם מכשיר והגדרתם אותו למשתמש.
  • הסבר על תהליך Ambient API: כדאי לעיין בתהליך Ambient API כדי להבין את התהליך הכולל, במיוחד את השלב שבו מתבצעת סקירה (polling) של mediaSourcesSet.

סקר עבור mediaSourcesSet

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

צריך לבצע מדי פעם קריאה ל-method‏ devices.get עבור deviceId הספציפי. עוקבים אחרי השדה mediaSourcesSet בתשובה AmbientDevice. בשלב הראשון, הערך יהיה false. אחרי שהמשתמש יבחר מקורות מדיה, השדה הזה ישתנה ל-true.

התשובה AmbientDevice כוללת pollingConfig עם pollInterval שמשמש להנחיה לגבי תדירות הסקרים.

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

אחרי ש-mediaSourcesSet הוא true במכשיר, אפשר להתחיל לאחזר את פריטי המדיה שבחר המשתמש.

  1. שימוש בנקודת הקצה mediaItems.list: שולחים בקשת GET אל https://photosambient.googleapis.com/v1/mediaItems, ומציינים את deviceId בנתיב.

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

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

    • id: המזהה הייחודי של פריט המדיה.
    • creationTime: חותמת הזמן שבה נוצר פריט המדיה.
    • mediaFile: אובייקט שמכיל פרטים לגישה לתוכן בפועל.

השדה mediaFile כולל את baseUrl. זהו הערך של baseUrl שבעזרתו תוכלו ליצור כתובות URL כדי לגשת לתוכן של פריט המדיה ברזולוציות או בפורמטים שונים.

כתובות 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‏, 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 בסיסיות של תמונות.

השלבים הבאים

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