يشرح هذا الدليل كيف تتيح Google Drive API عدة طرق للبحث عن الملفات والمجلدات.
يمكنك استخدام طريقة list في مورد
files لعرض كل ملفات ومجلدات مستخدم
Drive أو بعضها. يمكن أيضًا استخدام طريقة list لاسترداد fileId المطلوب لبعض طرق الموارد (مثل طريقة get وطريقة update).
استخدام مَعلمة fields
إذا أردت تحديد الحقول التي سيتم عرضها في الردّ، يمكنك ضبط الـ
fields مَعلمة
النظام
باستخدام أي طريقة من طرق مورد الـ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'
لعرض جميع عبارات البحث عن الملفات، يُرجى الاطّلاع على عبارات البحث الخاصة بالملفات.
لعرض جميع عوامل تشغيل طلب البحث التي يمكنك استخدامها لإنشاء طلب بحث، يُرجى الاطّلاع على Query operators.
أمثلة على سلاسل طلب البحث
يعرض الجدول التالي أمثلة على بعض سلاسل طلب البحث الأساسية. يختلف الرمز الفعلي حسب مكتبة العميل التي تستخدمها في بحثك.
عليك أيضًا إزالة الأحرف الخاصة في أسماء ملفاتك للتأكّد من أنّ طلب البحث يعمل بشكلٍ صحيح. على سبيل المثال، إذا كان اسم الملف يحتوي على كل من الفاصلة العليا
(') والشرطة المائلة للخلف ("\")، استخدِم شرطة مائلة للخلف لإزالتها: name
contains 'quinn\'s paper\\essay'.
| ما تريد طلبه | مثال |
|---|---|
| الملفات التي تحمل الاسم "hello" | name = 'hello' |
| الملفات التي يتضمّن اسمها الكلمتَين "hello" و"goodbye" | name contains 'hello' and name contains 'goodbye' |
| الملفات التي لا يتضمّن اسمها الكلمة "hello" | not name contains 'hello' |
| الملفات التي تحتوي على النص "important" والموجودة في المهملات | fullText contains 'important' and trashed = true |
| الملفات التي تحتوي على الكلمة "hello" | fullText contains 'hello' |
| الملفات التي لا تحتوي على الكلمة "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 |
| الملفات التي تمت مشاركتها مع المستخدم المفوّض والتي يتضمّن اسمها الكلمة "hello" | 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
space. عندما تعرض nextPageToken القيمة null، يعني ذلك أنّه ما مِن نتائج أخرى.
جافا
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'.
لمزيد من المعلومات، يُرجى الاطّلاع على البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنة.
البحث في المجموعات
تلقائيًا، يتم ضبط مجموعة عناصر user على مَعلمة طلب البحث corpora
عند استخدام طريقة list. للبحث في مجموعات عناصر أخرى، مثل تلك التي تمت مشاركتها مع domain، عليك ضبط المَعلمة corpora بشكلٍ صريح.
يمكنك البحث في مجموعات متعددة في طلب بحث واحد، ولكن إذا كانت المجموعات المدمَجة كبيرة جدًا، قد تعرض واجهة برمجة التطبيقات نتائج غير مكتملة. تحقَّق من الحقل
incompleteSearch
في نص الردّ. إذا كانت قيمته true، يعني ذلك أنّه تم حذف بعض المستندات. لحلّ هذه المشكلة، ضيّق نطاق corpora لاستخدام user أو drive.
عند استخدام مَعلمة طلب البحث
orderBy في طريقة list، تجنَّب استخدام المفتاح createdTime لطلبات البحث في مجموعات العناصر الكبيرة لأنّ ذلك يتطلّب معالجة إضافية وقد يؤدي إلى حدوث مهلات أو مشاكل أخرى. للفرز حسب الوقت في مجموعات العناصر الكبيرة، يمكنك استخدام modifiedTime بدلاً من ذلك لأنّه محسّن للتعامل مع طلبات البحث هذه.
على سبيل المثال، ?orderBy=modifiedTime.
إذا لم تحدّد مَعلمة طلب البحث orderBy، لن يكون هناك ترتيب فرز تلقائي وسيتم عرض العناصر بشكلٍ عشوائي.
مواضيع ذات صلة
- البحث عن مساحات التخزين السحابي المشتركة
- عبارات البحث وعوامل تشغيله
- أنواع MIME المتوافقة في Google Workspace وGoogle Drive
- الأدوار والأذونات
- البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنة