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
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

الفلاتر

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

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

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

يمكن تحديد قائمة بالفئات المراد تضمينها و/أو قائمة فئات لاستبعادها. داخل كل قائمة، يتم دمج الفئات مع 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) AND NOT (c3 OR c4). يجب ألا تظهر الفئة التي تظهر في includedContentategories في excludedContentCategories.

تمثيل JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
الحقول
includedContentCategories[]

enum (ContentCategory)

مجموعة الفئات المطلوب تضمينها في نتائج البحث عن عنصر الوسائط العناصر الموجودة في المجموعة هي OR. يُسمح بـ 10 includedContentCategories كحد أقصى لكل طلب.
excludedContentCategories[]

enum (ContentCategory)

مجموعة الفئات التي لن يتم تضمينها في نتائج البحث عن ملفات الوسائط. العناصر الموجودة في المجموعة هي OR. يُسمح بـ 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"