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

الفلاتر

الفلاتر التي يمكن تطبيقها على عملية بحث عن عنصر وسائط إذا تم تحديد خيارات فلترة متعددة، يتم التعامل معها على أنّها 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

في حال ضبط هذا الخيار، تتضمّن النتائج عناصر الوسائط التي أرشفها المستخدم. الإعداد التلقائي هو خطأ (لا يتم تضمين عناصر الوسائط المؤرشفة).
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)

مجموعة الميزات التي سيتم تضمينها في نتائج البحث عن عنصر الوسائط العناصر في المجموعة تعتمد على OR ويمكن أن تتطابق مع أي من الميزات المحددة.

الميزة

مجموعة الميزات التي يمكنك الفلترة حسبها

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