Method: mediaItems.search

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

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של 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 אם רק השנה משמעותית, למשל, שנת 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 או c2 או 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)

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

enum (ContentCategory)

קבוצת הקטגוריות שלא ייכללו בתוצאות החיפוש של פריטי המדיה. הפריטים בקבוצה מחוברים באמצעות 'או'. אפשר להגיש עד 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 וסוגי תמונות מיוחדים כמו תמונות Live Photos ב-iOS, תמונות 'תנועה' ב-Android, תמונות פנורמיות ותמונות Photo Sphere.

FeatureFilter

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

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

enum (Feature)

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

תכונה

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

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