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

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

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

סקירה כללית

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

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

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

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

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

בקשה ראשונה

{
  "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 שכבר היה בשימוש באותו מקום בקשה.