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

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

כדי להציג תוכן שנוצר על ידי אפליקציה, נדרש ההיקף photoslibrary.readonly.appcreateddata. מידע נוסף על היקפים זמין במאמר היקפי הרשאה.

סקירה כללית

Library API מאפשר לכם ליצור רשימה של פריטי מדיה שנוצרו על ידי האפליקציה שלכם ולגשת אליהם.

אלה כמה מהתכונות העיקריות של פרסום פריטים של מדיה:

  • הצגת רשימה של פריטי מדיה מאלבומים ספציפיים שנוצרו באפליקציה או מכל הספרייה שנוצרה באפליקציה

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

  • אחזור אובייקטים מסוג mediaItem עם פרטים חיוניים כמו קישורים ישירים ומטא-נתונים.

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

הצגת רשימה של אלבומים שנוצרו באפליקציה

אפשר להציג רשימה של אלבומים שנוצרו על ידי האפליקציה באמצעות albums.list.

REST

הנה בקשה לדוגמה:

GET https://photoslibrary.googleapis.com/v1/albums

הבקשה מחזירה את התוצאה הבאה:

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

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

השדה productUrl מפנה לאלבום ב-Google Photos שהמשתמש יכול לפתוח.

השדה coverPhotoMediaItemId מכיל את מזהה פריט המדיה שמייצג את תמונת השער של האלבום. כדי לגשת לתמונת השער הזו, משתמשים ב-coverPhotoBaseUrl. אין להשתמש ב-coverPhotoBaseUrl ישירות בלי לציין פרמטרים נוספים.

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

התשובה לאלבומים ריקים שונה, כי הערכים של mediaItemsCount ו-coverPhotoMediaItemId מוגדרים ל-0 כברירת מחדל והם לא נכללים בתשובה ל-REST. חשוב גם לציין ש-coverPhotoBaseUrl מפנה לתמונת placeholder שמוגדרת כברירת מחדל.

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

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

כדי להציג רשימה של פריטי מדיה, קוראים לפונקציה mediaItems.list.

REST

הנה דוגמה לבקשה:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

בתגובה לבקשת ה-GET מוחזרת התשובה הבאה:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

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

הצגת תוכן האלבום

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

REST

הנה דוגמה לבקשה:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

בתגובה לבקשת ה-POST מוחזרת התשובה הבאה:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

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

אם ההגדרה albumId מוגדרת, אי אפשר להחיל מסנן כשמציגים את תוכן האלבום. פעולה זו תגרום לשגיאה Bad Request.

חלוקה לדפים ב-REST

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

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

גודל הדף שמוגדר כברירת מחדל, והמומלץ, כשמציגים אלבומים, הוא 20 אלבומים, ואפשר לכלול עד 50 אלבומים.

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

דוגמה

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

בקשה מס' 1

{
  "pageSize": "5",
  "filters": { … }
}

תשובה מס' 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

בקשה מס' 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

תשובה מס' 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

צריך להמשיך את הדפוס הזה עד שלא יהיו יותר אובייקטים מסוג nextPageToken.

השדה nextPageToken תקף רק לאותה בקשה. אם משנים פרמטרים כלשהם, אסור להשתמש ב-nextPageToken ששימש בעבר באותה בקשה.