يوضّح هذا الدليل كيف تتيح Google Drive API عدة طرق للبحث عن الملفات والمجلدات.
يمكنك استخدام طريقة list
في مورد
files
لعرض كل أو بعض الملفات والمجلدات الخاصة بمستخدم Drive. يمكن أيضًا استخدام طريقة list
لاسترداد fileId
المطلوبة لبعض طرق الموارد (مثل طريقة get
وطريقة update
).
استخدام المَعلمة fields
إذا أردت تحديد الحقول التي سيتم عرضها في الردّ، يمكنك ضبط المَعلمة
fields
system
باستخدام أي طريقة من طرق المورد files
. في حال حذف المَعلمة fields
، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، تعرض الطريقة
list
الحقول kind
وid
وname
وmimeType
وresourceKey
فقط لكل ملف. لعرض حقول مختلفة، راجِع عرض حقول محدّدة.
الحصول على ملف
للحصول على ملف، استخدِم طريقة get
في مورد files
مع مَعلمة المسار fileId
.
إذا كنت لا تعرف معرّف الملف، يمكنك إدراج جميع الملفات باستخدام طريقة list
.
تعرض الطريقة الملف كمثيل لمورد files
. في حال توفير مَعلمة طلب البحث alt=media
، ستتضمّن الاستجابة محتوى الملف في نص الاستجابة. لتنزيل الملف أو تصديره، اطّلِع على تنزيل الملفات وتصديرها.
لإقرارك بمخاطر تنزيل برامج ضارة معروفة أو ملفات مسيئة أخرى، اضبط مَعلمة طلب البحث acknowledgeAbuse
على true
. لا ينطبق هذا الحقل إلا عندما يتم ضبط المَعلمة alt=media
ويكون المستخدم إما مالك الملف أو منظّم مساحة التخزين السحابي المشتركة التي يتضمّنها الملف.
البحث عن جميع الملفات والمجلدات في مجلد "ملفاتي" الخاص بالمستخدم الحالي
استخدِم طريقة list
بدون أي مَعلمات لعرض جميع الملفات والمجلدات.
GET https://www.googleapis.com/drive/v3/files
البحث عن ملفات أو مجلدات معيّنة في مجلد "ملفاتي" الخاص بالمستخدم الحالي
للبحث عن مجموعة محدّدة من الملفات أو المجلدات، استخدِم الحقل q
لسلسلة طلب البحث
مع الطريقة list
لفلترة الملفات التي سيتم عرضها
من خلال الجمع بين عبارة بحث واحدة أو أكثر.
تحتوي بنية سلسلة طلب البحث على الأجزاء الثلاثة التالية:
query_term operator values
المكان:
query_term
هي عبارة البحث أو الحقل الذي سيتم البحث فيه.تحدّد
operator
شرط عبارة البحث.values
هي القيم المحدّدة التي تريد استخدامها لفلترة نتائج البحث.
على سبيل المثال، يفلتر سلسلة طلب البحث التالية نتائج البحث لعرض المجلدات فقط من خلال ضبط نوع MIME:
q: mimeType = 'application/vnd.google-apps.folder'
للاطّلاع على جميع عبارات طلب البحث الخاصة بالملفات، يُرجى الاطّلاع على عبارات طلب البحث الخاصة بالملفات.
للاطّلاع على جميع عوامل تشغيل طلب البحث التي يمكنك استخدامها لإنشاء طلب بحث، راجِع عوامل تشغيل طلب البحث.
أمثلة على سلاسل طلبات البحث
يعرض الجدول التالي أمثلة على بعض سلاسل طلبات البحث الأساسية. يختلف الرمز الفعلي حسب مكتبة العميل التي تستخدمها للبحث.
يجب أيضًا إلغاء الأحرف الخاصة في أسماء الملفات للتأكّد من أنّ طلب البحث يعمل بشكل صحيح. على سبيل المثال، إذا كان اسم الملف يحتوي على كل من علامة اقتباس مفردة ('
) وعلامة شرطة مائلة عكسية ("\"
)، استخدِم علامة شرطة مائلة عكسية لتجنُّبها: name
contains 'quinn\'s paper\\essay'
.
ما تريد البحث عنه | مثال |
---|---|
الملفات التي تحمل الاسم "hello" | name = 'hello' |
الملفات التي يتضمّن اسمها الكلمتين "مرحبًا" و "وداعًا" | name contains 'hello' and name contains 'goodbye' |
الملفات التي لا يتضمّن اسمها الكلمة "hello" | not name contains 'hello' |
الملفات التي تحتوي على النص "مهم" والموجودة في المهملات | fullText contains 'important' and trashed = true |
الملفات التي تتضمّن الكلمة "مرحبًا" | fullText contains 'hello' |
الملفات التي لا تتضمّن الكلمة "مرحبًا" | not fullText contains 'hello' |
الملفات التي تحتوي على العبارة "hello world" بالضبط | fullText contains '"hello world"' |
الملفات التي تتضمّن طلب بحث يحتوي على الحرف "\" (مثل "\authors") | fullText contains '\\authors' |
الملفات التي تكون مجلدات | mimeType = 'application/vnd.google-apps.folder' |
الملفات التي ليست مجلدات | mimeType != 'application/vnd.google-apps.folder' |
الملفات التي تم تعديلها بعد تاريخ معيّن (المنطقة الزمنية التلقائية هي التوقيت العالمي المنسّق) | modifiedTime > '2012-06-04T12:00:00' |
ملفات الصور أو الفيديوهات التي تم تعديلها بعد تاريخ معيّن | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
الملفات المميّزة بنجمة | starred = true |
الملفات ضِمن مجموعة (على سبيل المثال، معرّف المجلد في المجموعة parents ) |
'1234567' in parents |
الملفات في مجلد بيانات التطبيق ضمن مجموعة | 'appDataFolder' in parents |
الملفات التي يكون المستخدم "test@example.org" هو مالكها | 'test@example.org' in owners |
الملفات التي يملك المستخدم "test@example.org" إذن الكتابة فيها | 'test@example.org' in writers |
الملفات التي يملك أعضاء المجموعة "group@example.org" إذن الكتابة فيها | 'group@example.org' in writers |
الملفات التي تمت مشاركتها مع المستخدم المعتمَد والتي يتضمّن اسمها كلمة "مرحبًا" | sharedWithMe and name contains 'hello' |
الملفات التي تتضمّن خاصية ملف مخصّصة مرئية لجميع التطبيقات | properties has { key='mass' and value='1.3kg' } |
الملفات التي تتضمّن سمة ملف مخصّصة خاصة بالتطبيق الذي يطلب الوصول إليها | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
الملفات التي لم تتم مشاركتها مع أي مستخدمين أو نطاقات (خاصة فقط أو تمت مشاركتها مع مستخدمين أو مجموعات محدّدة) | visibility = 'limited' |
فلترة نتائج البحث باستخدام مكتبة برامج
يوضّح نموذج الرمز البرمجي التالي كيفية استخدام مكتبة برامج للعملاء من أجل فلترة نتائج البحث حسب أسماء الملفات ومعرّفات ملفات JPEG. يستخدم هذا المثال عبارة البحث mimeType
لحصر النتائج بالملفات من النوع image/jpeg
. يتم أيضًا ضبط
spaces
على drive
لتضييق نطاق البحث أكثر ليقتصر على مساحة Drive. عندما تعرض الدالة nextPageToken
القيمة null
،
يعني ذلك أنّه لم تعُد هناك نتائج أخرى.
Java
Python
Node.js
PHP
البحث عن ملفات تتضمّن خاصية ملف مخصّصة
للبحث عن ملفات تتضمّن خاصية ملف مخصّصة، استخدِم عبارة البحث properties
أو appProperties
مع مفتاح وقيمة. على سبيل المثال، للبحث عن خاصية ملف مخصّصة خاصة بالتطبيق الذي يرسل الطلب واسمها additionalID
وقيمتها 8e8aceg2af2ge72e78
، اتّبِع الخطوات التالية:
appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
لمزيد من المعلومات، يُرجى الاطّلاع على إضافة خصائص ملفات مخصّصة.
البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنة
للبحث عن ملفات تحمل تصنيفات معيّنة، استخدِم عبارة البحث labels
مع معرّف تصنيف معيّن. على سبيل المثال: 'labels/LABEL_ID' in
labels
. إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على جميع مثيلات الملفات التي تم تطبيق التصنيف عليها.
للبحث عن ملفات بدون رقم تعريف تصنيف معيّن: Not
'labels/LABEL_ID' in labels
.
يمكنك أيضًا البحث عن الملفات استنادًا إلى قيم حقول معيّنة. على سبيل المثال، للبحث عن ملفات تتضمّن قيمة نصية:
labels/LABEL_ID.text_field_id ='TEXT'
.
لمزيد من المعلومات، يمكنك الاطّلاع على البحث عن ملفات باستخدام تصنيف أو قيمة حقل معيّنَين.
البحث في مجموعات النصوص
تستخدم عمليات البحث التي تستدعي الطريقة list
corpora
من user
تلقائيًا. للبحث في مجموعات نصوص أخرى، مثل الملفات التي تمت مشاركتها مع domain
، اضبط المَعلمة corpora
.
يمكن البحث في عدة مجموعات في طلب بحث واحد، ولكن قد يتم عرض نتائج غير مكتملة إذا كانت المجموعات المدمجة كبيرة جدًا. إذا كان incompleteSearch
true
في نص الرد، يعني ذلك أنّه لم يتم عرض جميع المستندات. في حال حدوث ذلك، عليك تضييق نطاق بحثك من خلال اختيار مجموعة نصوص مختلفة، مثل user
أو drive
.
مواضيع ذات صلة
- البحث عن مساحات تخزين سحابي مشتركة
- عبارات البحث وعوامل التشغيل
- أنواع MIME المتوافقة في Google Workspace وGoogle Drive
- الأدوار والأذونات
- البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنَين