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

فلاتر

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

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

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

FeatureFilter

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

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

enum (Feature)

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

الميزة

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

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