يوضّح هذا الدليل كيف تتيح 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'
لعرض جميع عبارات البحث عن الملفات، يُرجى الاطّلاع على عبارات البحث الخاصة بالملفات.
لعرض جميع عوامل تشغيل البحث التي يمكنك استخدامها لإنشاء طلب بحث، يُرجى الاطّلاع على عوامل تشغيل البحث.
أمثلة على سلاسل طلب البحث
يعرض الجدول التالي أمثلة على بعض سلاسل طلب البحث الأساسية. يختلف الرمز الفعلي حسب مكتبة العميل التي تستخدمها في بحثك.
عليك أيضًا إزالة الأحرف الخاصة في أسماء ملفاتك للتأكّد من أنّ طلب البحث يعمل بشكلٍ صحيح. على سبيل المثال، إذا كان اسم الملف يحتوي على كل من الفاصلة العليا
(') والشرطة المائلة للخلف ("\")، استخدِم شرطة مائلة للخلف لإزالتهما: 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. عندما تعرض 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
- الأدوار والأذونات
- البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنة