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
  • 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 או c2 או c3).

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

בדוגמה הקודמת, המערכת תציג פריטים של מדיה שמכילים את (c1 או c2) ולא את (c3 או 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.