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 أو 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)

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