Method: mediaItems.search

البحث عن عناصر وسائط في مكتبة "صور Google" الخاصة بالمستخدم في حال عدم ضبط أي فلاتر، يتم عرض جميع عناصر الوسائط في مكتبة المستخدم. في حال ضبط ألبوم، يتم عرض جميع عناصر الوسائط في الألبوم المحدّد. في حال تحديد فلاتر، يتم إدراج عناصر الوسائط التي تتطابق مع الفلاتر من مكتبة المستخدم. في حال ضبط كل من الألبوم والفلاتر، سيؤدي الطلب إلى حدوث خطأ.

طلب 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

الفلاتر

الفلاتر التي يمكن تطبيقها على عملية بحث عن عنصر وسائط في حال تحديد خيارات فلاتر متعدّدة، يتم التعامل معها على أنّها عامل تشغيل "و" مع بعضها.

تمثيل 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

وفي حال ضبطها، ستتضمّن النتائج ملفات الوسائط التي وضعها المستخدم في الأرشيف. يتم ضبط الإعدادات التلقائية على "خطأ" (لا يتم تضمين ملفات الوسائط المؤرشفة).
excludeNonAppCreatedData

boolean

في حال ضبط هذا الخيار، تستبعد النتائج عناصر الوسائط التي لم ينشئها هذا التطبيق. الإعداد التلقائي هو خطأ (يتم عرض جميع عناصر الوسائط). يتم تجاهل هذا الحقل في حال استخدام النطاق photoslibrary.readonly.appcreateddata.

DateFilter

يحدِّد هذا الفلتر التواريخ أو النطاقات الزمنية المسموح بها للوسائط التي يتم عرضها. ويمكنك اختيار مجموعة من التواريخ المحدّدة والنطاقات الزمنية. بالنسبة إلى طلبات البحث التي تستخدم فلاتر التاريخ، فإنّ عناصر الوسائط التي تم تحميلها بدون بيانات وصفية تحدِّد تاريخ التقاط الوسائط لن يتم عرضها. لا يتم استخدام وقت التحميل من خادم "صور Google" كإجراء احتياطي في هذه الحالة.

تمثيل 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

يتيح لك هذا الفلتر عرض عناصر الوسائط استنادًا إلى نوع المحتوى.

من الممكن تحديد قائمة بالفئات المطلوب تضمينها و/أو قائمة بالفئات المطلوب استبعادها. ضمن كل قائمة، يتم دمج الفئات باستخدام عامل التشغيل "أو".

فلتر المحتوى includedContentCategories: [c1, c2, c3] سيحصل على عناصر الوسائط التي تحتوي على (c1 OR c2 OR 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

هذه مجموعة من فئات المحتوى المحدّدة مسبقًا التي يمكنك الفلترة حسبها.

عمليات التعداد
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

مجموعة أنواع الوسائط التي يمكن البحث عنها.

عمليات التعداد
ALL_MEDIA يتم التعامل معها كما لو لم يتم تطبيق أي فلاتر. يتم تضمين جميع أنواع الوسائط.
VIDEO جميع عناصر الوسائط التي تُعتبر فيديوهات ويشمل ذلك أيضًا الأفلام التي أنشأها المستخدم باستخدام تطبيق "صور Google".
PHOTO جميع عناصر الوسائط التي تُعدّ صورًا ويشمل ذلك تنسيقات ‎ .bmp و‎.gif و‎.ico و‎.jpg (والصيغ الأخرى) و‎.tiff و‎.webp وأنواع الصور الخاصة، مثل الصور الحية على أجهزة iOS والصور المتحركة على أجهزة Android والصور البانورامية والصور البانورامية 360 درجة.

FeatureFilter

يحدِّد هذا الفلتر الميزات التي يجب أن تمتلكها عناصر الوسائط.

تمثيل JSON 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
الحقول
includedFeatures[]

enum (Feature)

مجموعة الميزات التي سيتم تضمينها في نتائج البحث عن ملفات الوسائط يتمّ ربط العناصر في المجموعة باستخدام "أو" وقد تتطابق مع أيٍّ من الميزات المحدّدة.

الميزة

مجموعة الميزات التي يمكنك الفلترة وفقًا لها.

عمليات التعداد
NONE يتم التعامل معها كما لو لم يتم تطبيق أي فلاتر. تشمل الإقامة جميع الميزات.
FAVORITES عناصر الوسائط التي وضع عليها المستخدم علامة "مفضّلة" في تطبيق "صور Google"