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

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

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

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

סקר מספר mediaSourcesSet

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

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

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

List Media Items

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

דוגמה להצגת פריט מדיה ברוחב של עד 2,048 פיקסלים ובגובה של עד 1,024 פיקסלים:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

תיאור

הפרמטר c לחיתוך.

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

תיאור

הפרמטר download, ‏ 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.

לדוגמה:

דוגמאות מופיעות בטבלה של כתובות בסיס של תמונות.
no

תיאור

הפרמטר להסרת שכבת-העל של התמונה הממוזערת, no.

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

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

לדוגמה:

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

מדיניות תוכן וסינון

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

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

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

השלבים הבאים

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