Method: mediaItems.search

موارد رسانه ای را در کتابخانه Google Photos کاربر جستجو می کند. اگر هیچ فیلتری تنظیم نشده باشد، تمام موارد رسانه ای در کتابخانه کاربر برگردانده می شوند. اگر آلبومی تنظیم شده باشد، همه موارد رسانه در آلبوم مشخص شده برگردانده می شوند. اگر فیلترها مشخص شده باشند، موارد رسانه ای که با فیلترهای کتابخانه کاربر مطابقت دارند فهرست می شوند. اگر هم آلبوم و هم فیلترها را تنظیم کنید، درخواست با خطا مواجه می شود.

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی 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 استفاده شود، این قسمت نادیده گرفته می شود.

فیلتر تاریخ

این فیلتر تاریخ ها یا محدوده های تاریخ مجاز را برای رسانه بازگشتی تعریف می کند. امکان انتخاب مجموعه ای از تاریخ های خاص و مجموعه ای از محدوده های تاریخ وجود دارد. موارد رسانه ای آپلود شده بدون ابرداده که تاریخ ضبط مورد رسانه را مشخص می کند، در جستارهایی با استفاده از فیلترهای تاریخ بازگردانده نمی شوند. در این مورد از زمان آپلود سرور 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 باشد.

محدوده تاریخ

محدوده ای از تاریخ ها را تعریف می کند. هر دو تاریخ باید از یک قالب باشند. برای اطلاعات بیشتر، به 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) و NOT (c3 OR c4) هستند. دسته ای که در includedContentategories ظاهر می شود نباید در excludedContentCategories ظاهر شود.

نمایندگی JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
فیلدها
includedContentCategories[]

enum ( ContentCategory )

مجموعه دسته بندی هایی که باید در نتایج جستجوی آیتم های رسانه ای گنجانده شوند. اقلام موجود در مجموعه ORed هستند. در هر درخواست حداکثر 10 includedContentCategories شده است.

excludedContentCategories[]

enum ( ContentCategory )

مجموعه ای از مقوله هایی که نباید در نتایج جستجوی آیتم های رسانه ای گنجانده شوند. اقلام موجود در مجموعه ORed هستند. در هر درخواست حداکثر 10 excludedContentCategories وجود دارد.

دسته بندی محتوا

این مجموعه ای از دسته بندی های محتوای از پیش تعریف شده است که می توانید بر روی آنها فیلتر کنید.

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، پانوراما، فوتوسفر است.

فیلتر ویژگی

این فیلتر ویژگی هایی را که آیتم های رسانه باید داشته باشند را مشخص می کند.

نمایندگی JSON 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
فیلدها
includedFeatures[]

enum ( Feature )

مجموعه ویژگی هایی که باید در نتایج جستجوی آیتم رسانه گنجانده شوند. اقلام موجود در مجموعه OR شده اند و ممکن است با هر یک از ویژگی های مشخص شده مطابقت داشته باشند.

ویژگی

مجموعه ای از ویژگی هایی که می توانید روی آنها فیلتر کنید.

Enums
NONE طوری رفتار می شود که انگار هیچ فیلتری اعمال نشده است. تمام ویژگی ها گنجانده شده است.
FAVORITES موارد رسانه ای که کاربر در برنامه Google Photos به عنوان موارد دلخواه علامت گذاری کرده است.