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 כ-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)

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

FeatureFilter

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

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

enum (Feature)

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

תכונה

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

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