Method: mediaItems.search

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

בקשת HTTP

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
שדות
albumId

string

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

integer

המספר המקסימלי של פריטי מדיה שיוחזרו בתגובה. ייתכן שיוחזרו פחות פריטי מדיה מהמספר שצוין. ערך ברירת המחדל של pageSize הוא 25 והערך המקסימלי הוא 100.
pageToken

string

אסימון המשך לקבלת הדף הבא של התוצאות. הוספה של ערך זה לבקשה תחזיר את השורות אחרי pageToken. pageToken צריך להיות הערך שהוחזר בפרמטר nextPageToken בתגובה לבקשה של searchMediaItems.
filters

object (Filters)

המסננים שיחולו על הבקשה. לא ניתן להגדיר בשילוב עם albumId.
orderBy

string

שדה אופציונלי לציון סדר המיון של תוצאות החיפוש. השדה orderBy פועל רק כשמשתמשים בdateFilter. אם לא מציינים את השדה הזה, התוצאות מוצגות מהחדשה לישנה, מהישן לחדש ביותר creationTime. אם מספקים את הערך MediaMetadata.creation_time, תוצאות החיפוש מוצגות בסדר ההפוך, מהישן לחדש ביותר. כדי להציג את התוצאות מהחדשה לישנה ולישן ביותר, יש לכלול את הארגומנט desc באופן הבא: MediaMetadata.creation_time desc.

המסננים הנוספים היחידים שאפשר להשתמש בהם עם הפרמטר הזה הם includeArchivedMedia ו-excludeNonAppCreatedData. אין תמיכה במסננים אחרים.

גוף התשובה

רשימה של פריטי מדיה שתואמים לפרמטרים של החיפוש.

אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
שדות
mediaItems[]

object (MediaItem)

פלט בלבד. רשימה של פריטי מדיה שתואמים לפרמטרים של החיפוש.
nextPageToken

string

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata

מסננים

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

ייצוג JSON 
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
שדות
dateFilter

object (DateFilter)

סינון פריטי המדיה לפי תאריך היצירה שלהם.
contentFilter

object (ContentFilter)

סינון פריטי המדיה על סמך התוכן שלהם.
mediaTypeFilter

object (MediaTypeFilter)

סינון של פריטי המדיה לפי סוג המדיה.
featureFilter

object (FeatureFilter)

סינון פריטי המדיה לפי התכונות שלהם.
includeArchivedMedia

boolean

אם המדיניות מוגדרת, התוצאות יכללו פריטי מדיה שהמשתמש העביר לארכיון. ברירת המחדל היא False (פריטי מדיה שהועברו לארכיון לא נכללים).
excludeNonAppCreatedData

boolean

אם המדיניות מוגדרת, התוצאות לא יכללו פריטי מדיה שלא נוצרו על ידי האפליקציה הזו. ערך ברירת המחדל הוא False (כל פריטי המדיה מוחזרים). המערכת מתעלמת מהשדה הזה אם נעשה שימוש בהיקף photoslibrary.readonly.appcreateddata.

DateFilter

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

ייצוג JSON 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
שדות
dates[]

object (Date)

רשימת תאריכים שתואמים לתאריך היצירה של פריטי המדיה. ניתן לכלול עד 5 תאריכים לכל בקשה.
ranges[]

object (DateRange)

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

תאריך

מייצג תאריך שלם ביומן. יש להגדיר את day כ-0 אם רק החודש והשנה משמעותיים, למשל כל דצמבר 2018. יש להגדיר את day ואת month ל-0 אם רק השנה משמעותית, למשל כל שנת 2018. יש להגדיר את year ל-0 אם רק היום והחודש משמעותיים, למשל יום נישואין או יום הולדת.

לא נתמך: אם כל הערכים מוגדרים ל-0, רק ל-month או ל-0, או גם ל-day וגם ל-year בו-זמנית.

ייצוג JSON 
{
  "year": integer,
  "month": integer,
  "day": integer
}
שדות
year

integer

שנת התאריך. חייב להיות בין 1 ל-9999, או 0 כדי לציין תאריך ללא שנה.
month

integer

חודש בשנה. חייב להיות בין 1 ל-12, או 0 כדי לציין שנה ללא חודש ויום.
day

integer

היום בחודש. הערך צריך להיות בין 1 ל-31 והוא תקף לשנה ולחודש, או 0 אם מציינים שנה בחודש שבה היום לא משמעותי.

DateRange

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

ייצוג JSON 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
שדות
startDate

object (Date)

תאריך ההתחלה (כלול כחלק מהטווח) באחד מהפורמטים המתוארים.
endDate

object (Date)

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

ContentFilter

מסנן זה מאפשר להציג פריטי מדיה על סמך סוג התוכן.

ניתן לציין רשימת קטגוריות להכללה ו/או רשימת קטגוריות לאי הכללה. בתוך כל רשימה, הקטגוריות משולבות באופרטור OR.

מסנן התוכן includedContentCategories: [c1, c2, c3] יקבל פריטי מדיה שמכילים (c1 OR c2 OR c3).

מסנן התוכן excludedContentCategories: [c1, c2, c3] לא יקבל פריטי מדיה שמכילים (c1 OR c2 OR c3).

ניתן גם לכלול קטגוריות מסוימות מבלי לכלול קטגוריות אחרות, כמו בדוגמה הזו: includedContentCategories: [c1, c2], excludedContentCategories: [c3, c4]

בדוגמה הקודמת יתקבלו פריטי מדיה שמכילים (c1 OR c2) AND NOT (c3 OR c4). קטגוריה שמופיעה בincludedContentategories לא יכולה להופיע בexcludedContentCategories.

ייצוג JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
שדות
includedContentCategories[]

enum (ContentCategory)

קבוצת הקטגוריות שייכללו בתוצאות החיפוש של פריטי מדיה. הפריטים בקבוצה הם OR. אפשר להזין עד 10 includedContentCategories לכל בקשה.
excludedContentCategories[]

enum (ContentCategory)

קבוצת הקטגוריות שלא ייכללו בתוצאות החיפוש של פריטי מדיה. הפריטים בקבוצה הם OR. אפשר להזין עד 10 excludedContentCategories לכל בקשה.

ContentCategory

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

טיפוסים בני מנייה (enums)
NONE קטגוריית התוכן שמוגדרת כברירת מחדל. המערכת מתעלמת מקטגוריה זו כאשר נעשה שימוש בכל קטגוריה אחרת במסנן.
LANDSCAPES פריטי מדיה עם תמונות לרוחב.
RECEIPTS פריטי מדיה שמכילים קבלות.
CITYSCAPES פריטי מדיה הכוללים נופים עירוניים.
LANDMARKS פריטי מדיה שמכילים ציוני דרך.
SELFIES פריטי מדיה שהם תמונות סלפי.
PEOPLE פריטי מדיה שמכילים אנשים.
PETS פריטי מדיה שמכילים חיות מחמד.
WEDDINGS פריטי מדיה מחתונות.
BIRTHDAYS פריטי מדיה מימי הולדת.
DOCUMENTS פריטי מדיה שמכילים מסמכים.
TRAVEL פריטי מדיה שצולמו במהלך נסיעה.
ANIMALS פריטי מדיה שמכילים בעלי חיים.
FOOD פריטי מדיה שמכילים אוכל.
SPORT פריטי מדיה מאירועי ספורט.
NIGHT פריטי מדיה שצולמו בלילה.
PERFORMANCES פריטי מדיה מביצועים.
WHITEBOARDS פריטי מדיה שמכילים לוחות אינטראקטיבים.
SCREENSHOTS פריטי מדיה שהם צילומי מסך.
UTILITY פריטי מדיה שנחשבים לשימושי. האיסורים האלה כוללים, בין היתר, מסמכים, צילומי מסך, לוחות אינטאקטיביים.
ARTS פריטי מדיה שמכילים אומנות.
CRAFTS פריטי מדיה שכוללים מלאכת יד.
FASHION פריטי מדיה שקשורים לאופנה.
HOUSES פריטי מדיה שמכילים בתים.
GARDENS פריטי מדיה עם גנים.
FLOWERS פריטי מדיה שמכילים פרחים.
HOLIDAYS פריטי מדיה שצולמו בחגים.

MediaTypeFilter

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

ייצוג JSON 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
שדות
mediaTypes[]

enum (MediaType)

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

MediaType

קבוצת סוגי המדיה שניתן לחפש.

טיפוסים בני מנייה (enums)
ALL_MEDIA נחשב כאילו לא הוחלו מסננים. כל סוגי המדיה כלולים.
VIDEO כל פריטי המדיה שנחשבים לסרטונים. התוכן הזה כולל גם סרטים שהמשתמש יצר באמצעות אפליקציית Google Photos.
PHOTO כל פריטי המדיה שנחשבים לתמונות. הנחיה זו כוללת את .bmp, .gif, .ico, .jpg (ואיותים אחרים), .tiff, .webp וסוגים מיוחדים של תמונות, כגון תמונות חיות ב-iOS, תמונות עם תנועה ב-Android, תמונות פנורמה וצילום פנורמי.

FeatureFilter

המסנן הזה מגדיר את התכונות שפריטי המדיה אמורים לכלול.

ייצוג JSON 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
שדות
includedFeatures[]

enum (Feature)

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

תכונה

קבוצת התכונות שלפיהן ניתן לסנן.

טיפוסים בני מנייה (enums)
NONE נחשב כאילו לא הוחלו מסננים. כל התכונות כלולות.
FAVORITES פריטי מדיה שהמשתמש סימן כמועדפים באפליקציית Google Photos.