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
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

מסננים

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

ייצוג 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 או c2 או 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

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

טיפוסים בני מנייה (enum)
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

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

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

FeatureFilter

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

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

enum (Feature)

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

תכונה

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

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