يوضّح هذا الدليل كيف تتيح 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' |
| الملفات التي يتضمّن اسمها الكلمتين "hello" و "goodbye" | 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
- الأدوار والأذونات
- البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنَين