يوضّح هذا الدليل كيف تتيح Google Drive API عدة طرق للبحث عن الملفات والمجلدات.
يمكنك استخدام طريقة list في مورد
files لعرض كل أو بعض ملفات ومجلدات مستخدم
Drive. يمكنك أيضًا استخدام list
method لاسترداد fileId المطلوب لبعض طرق الموارد (مثل
get و update methods).
استخدام مَعلمة fields
إذا أردت تحديد الحقول التي سيتم عرضها في الردّ، يمكنك ضبط الـ
fields مَعلمة
النظام
باستخدام أي طريقة من طرق مورد الـfiles. إذا لم تحدّد مَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض طريقة
list سوى الحقول kind وid و
name وmimeType وresourceKey لكل ملف. لعرض حقول مختلفة
، يُرجى الاطّلاع على مقالة عرض حقول معيّنة.
الحصول على ملف حسب رقم تعريفه
للحصول على ملف، استخدِم طريقة get في مورد
files مع مَعلمة المسار fileId.
إذا لم يكن لديك رقم تعريف الملف، يمكنك عرض جميع الملفات باستخدام طريقة list.
تعرض الطريقة الملف كمثال لمورد files. إذا قدّمت المَعلمة alt=media، سيتضمّن الردّ محتوى الملف في نص الردّ. لتنزيل ملف ثنائي كبير، يُرجى الاطّلاع على مقالة تنزيل محتوى ملف ثنائي كبير.
لإقرار خطر تنزيل برامج ضارة معروفة أو ملفات أخرى
مسيئة، اضبط مَعلمة طلب البحث
acknowledgeAbuse على true. لا ينطبق هذا الحقل إلا عند ضبط المَعلمة alt=media وكان المستخدم إما مالك الملف أو منظِّم مساحة التخزين السحابي المشتركة التي يتوفّر فيها الملف.
عرض جميع الملفات والمجلدات في "ملفاتي"
استخدِم طريقة list بدون أي مَعلمات لعرض جميع الملفات والمجلدات في "ملفاتي" لدى المستخدم الحالي.
يوضّح أمر curl التالي كيفية عرض جميع الملفات:
curl -X GET \
'https://www.googleapis.com/drive/v3/files' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'
استبدِل ACCESS_TOKEN برمز دخول OAuth 2.0 مُرخَّص .
البحث عن ملفات ومجلدات معيّنة في "ملفاتي"
للبحث عن مجموعة معيّنة من الملفات أو المجلدات في "ملفاتي" لدى المستخدم الحالي، استخدِم حقل سلسلة طلب البحث q مع طريقة list لفلترة الملفات التي سيتم عرضها من خلال الجمع بين
عبارة بحث واحدة أو أكثر.
يحتوي تركيب سلسلة طلب البحث على الأجزاء الثلاثة التالية:
query_term operator values
المكان:
query_termهي عبارة البحث أو الحقل الذي سيتم البحث فيه.operatorتحدّد الشرط لعبارة البحث.valuesهي القيم المحدّدة التي تريد استخدامها لفلترة نتائج بحثك.
على سبيل المثال، يفلتر طلب البحث التالي عملية البحث لعرض المجلدات فقط من خلال ضبط نوع MIME:
mimeType = 'application/vnd.google-apps.folder'
للاطّلاع على جميع عبارات طلب البحث عن الملفات، يُرجى الاطّلاع على عبارات طلب البحث الخاصة بالملفات.
للاطّلاع على جميع عوامل تشغيل طلب البحث التي يمكنك استخدامها لإنشاء طلب بحث، يُرجى الاطّلاع على عوامل تشغيل طلب البحث.
أمثلة على سلاسل طلب البحث
يعرض الجدول التالي أمثلة على بعض سلاسل طلبات البحث الأساسية. يختلف الرمز الفعلي حسب مكتبة العميل التي تستخدمها في بحثك.
عليك أيضًا إزالة الأحرف الخاصة في أسماء ملفاتك للتأكّد من أنّ طلب البحث يعمل بشكلٍ صحيح. على سبيل المثال، إذا كان اسم الملف يحتوي على كل من الفاصلة العليا
(') والشرطة المائلة للخلف ("\")، استخدِم شرطة مائلة للخلف لإزالة تأثيرهما: name
contains 'quinn\'s paper\\essay'.
| ما الذي يجب طلبه | مثال |
|---|---|
عامل تشغيل مطابقة السلسلة (contains) |
|
| الملفات التي تحتوي على الكلمة "hello" | fullText contains 'hello' |
| الملفات التي تحتوي على العبارة "hello world" بالضبط | fullText contains '"hello world"' |
| الملفات التي تحتوي على طلب بحث يتضمّن الحرف "\" (على سبيل المثال، "\authors") | fullText contains '\\authors' |
| الملفات التي يحتوي اسمها على "budget" | name contains 'budget' |
عوامل تشغيل المساواة وعدم المساواة (=، !=) |
|
| الملفات التي تحمل الاسم "hello" | name = 'hello' |
| الملفات التي هي مجلدات | mimeType = 'application/vnd.google-apps.folder' |
| الملفات التي ليست مجلدات | mimeType != 'application/vnd.google-apps.folder' |
| الملفات المميّزة بنجمة | starred = true |
| الملفات في "المهملات" | trashed = true |
| الملفات التي ليست في "المهملات" | trashed = false |
| الاختصارات التي تشير إلى رقم تعريف ملف معيّن | shortcutDetails.targetId = '1987654321' |
| الملفات التي لم تتم مشاركتها مع أي مستخدم أو نطاقات (خاصة أو تمت مشاركتها مع مستخدمين أو مجموعات معيّنة) | visibility = 'limited' |
| الملفات التي يمكن لأي شخص الوصول إليها عبر الرابط | visibility = 'anyoneWithLink' |
| الملفات التي يمكن العثور عليها علنًا على الويب | visibility = 'anyoneCanFind' |
عوامل تشغيل المقارنة (>، >=، <، <=) |
|
| الملفات التي تم تعديلها بعد تاريخ معيّن (المنطقة الزمنية التلقائية هي التوقيت العالمي المنسَّق) | modifiedTime > '2012-06-04T12:00:00' |
| الملفات التي تم إنشاؤها بعد 1 يناير 2023 | createdTime > '2023-01-01T00:00:00' |
| الملفات التي تم تعديلها قبل 1 يناير 2023 | modifiedTime < '2023-01-01T00:00:00' |
عامل تشغيل عضوية المجموعة (in) |
|
الملفات الفرعية المباشرة ضمن مجموعة (على سبيل المثال، رقم تعريف المجلد في مجموعة 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 |
| الملفات التي يملك المستخدم "test@example.org" إذن القراءة فيها | 'test@example.org' in readers |
عامل تشغيل مطابقة المجموعة (has) |
|
| الملفات التي تحتوي على سمة ملف مخصّصة مرئية لجميع التطبيقات | properties has { key='mass' and value='1.3kg' } |
| الملفات التي تحتوي على سمة ملف مخصّصة خاصة بالتطبيق الذي يرسل الطلب | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
| الملفات التي تحتوي على سمة ملف مخصّصة بالكلمة الرئيسية "department" (بغض النظر عن القيمة) | properties has { key='department' } |
عوامل التشغيل المنطقية (and, or, not) |
|
| الملفات التي يحتوي اسمها على الكلمتَين "hello" و"goodbye" | name contains 'hello' and name contains 'goodbye' |
| الملفات التي لا يحتوي اسمها على الكلمة "hello" | not name contains 'hello' |
| الملفات التي تحتوي على النص "important" والموجودة في "المهملات" | fullText contains 'important' and trashed = true |
| الملفات التي لا تحتوي على الكلمة "hello" | not fullText contains 'hello' |
| ملفات الصور أو الفيديو التي تم تعديلها بعد تاريخ معيّن | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
| الملفات التي تمت مشاركتها مع المستخدم المفوَّض والتي يحتوي اسمها على "hello" | sharedWithMe and name contains 'hello' |
| الملفات التي هي مجلدات أو اختصارات | mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut' |
| الملفات التي تحمل الاسم "Project Plan" وليست في "المهملات" | name = 'Project Plan' and trashed = false |
| الملفات الفرعية المباشرة في مجلد معيّن وليست في "المهملات" | '1234567' in parents and trashed = false |
فلترة نتائج البحث باستخدام مكتبة عميل
يوضّح عينة التعليمات البرمجية التالية كيفية استخدام مكتبة عميل لفلترة نتائج البحث حسب أسماء الملفات وأرقام تعريف ملفات JPEG. يستخدِم هذا النموذج عبارة طلب البحث mimeType لحصر النتائج بالملفات من النوع image/jpeg. يضبط أيضًا
spaces على drive لتضييق نطاق البحث أكثر ليقتصر على
مساحة Drive. عندما يعرض nextPageToken القيمة null، يعني ذلك أنّه ما مِن نتائج أخرى.
جافا
Python
Node.js
PHP
عرض الملفات في مجلد علني
للبحث عن الملفات أو عرضها في مجلد تمت مشاركته علنًا (حيث تم ضبط إذن الوصول على
"أي شخص لديه الرابط" أو "علني على الويب")، استخدِم طريقة list في مورد files مع ضبط مَعلمة طلب البحث q للفلترة حسب رقم تعريف المجلد في مجموعة parents
'FOLDER_ID' in parents and trashed = false
عند عرض الملفات في مجلد علني، يمكنك مصادقة الطلبات باستخدام
مفتاح واجهة برمجة التطبيقات بدلاً من
بيانات اعتماد مستخدم OAuth 2.0. إذا كان المجلد موجودًا في مساحة تخزين سحابي مشتركة، عليك أيضًا ضبط supportsAllDrives=true وincludeItemsFromAllDrives=true في الطلب.
تعرض عينات التعليمات البرمجية التالية كيفية عرض الملفات في مجلد علني:
Node.js
/**
* List files in a public folder using an API key.
* @param {string} folderId The ID of the public folder.
* @param {string} apiKey Your Google Cloud API key.
* @return {Promise<Array>} The list of files.
*/
async function listPublicFolder(folderId, apiKey) {
const {google} = require('googleapis');
const service = google.drive({version: 'v3', auth: apiKey});
try {
const response = await service.files.list({
q: `'${folderId}' in parents and trashed = false`,
fields: 'nextPageToken, files(id, name, mimeType)',
supportsAllDrives: true,
includeItemsFromAllDrives: true,
});
const files = response.data.files;
console.log('Files:');
for (const file of files) {
console.log(`${file.name} (${file.id})`);
}
return files;
} catch (err) {
// TODO(developer): Handle error
console.error(err);
}
}
curl
curl -G \
'https://www.googleapis.com/drive/v3/files' \
--data-urlencode "q='FOLDER_ID' in parents and trashed = false" \
--data-urlencode 'supportsAllDrives=true' \
--data-urlencode 'includeItemsFromAllDrives=true' \
--data-urlencode 'fields=nextPageToken,files(id,name,mimeType)' \
--data-urlencode 'key=API_KEY' \
-H 'Accept: application/json'
غيِّر القيم في السلسلة على الشكل التالي:
- FOLDER_ID: رقم تعريف المجلد العلني
- API_KEY: مفتاح واجهة برمجة التطبيقات لمشروعك.
البحث عن المجلدات والملفات الفرعية بشكلٍ متكرّر
لا تعرض عبارة طلب البحث parents سوى الملفات والمجلدات الفرعية المباشرة الموجودة في المجلد المحدّد. لا توفّر Drive API عامل تشغيل أو مَعلمة لطلب البحث للبحث بشكلٍ متكرّر عن أشجار المجلدات الفرعية الفرعية في طلب بيانات من واجهة برمجة التطبيقات واحد.
للبحث عن مجلد وجميع المجلدات والملفات الفرعية الفرعية، يجب أن ينفّذ تطبيقك عملية اجتياز شجرة من جهة العميل:
- اطلب الملفات الفرعية المباشرة للمجلد المستهدَف باستخدام
'FOLDER_ID' in parents and trashed = false. - حدِّد المجلدات الفرعية من خلال فلترة النتائج التي يكون فيها
mimeType = 'application/vnd.google-apps.folder'. - اطلب بشكلٍ متكرّر أو تكراري رقم تعريف كل مجلد فرعي لاسترداد محتوياته.
توضّح عينات التعليمات البرمجية التالية كيفية البحث بشكلٍ متكرّر عن مجلد وعناصره التابعة:
Node.js
/**
* Recursively searches a folder and all descendant subfolders for files.
* @param {string} folderId The ID of the starting folder.
* @param {Object} authClient An authorized OAuth 2.0 client.
* @return {Promise<Array>} The list of all descendant files.
*/
async function searchFolderRecursively(folderId, authClient) {
const {google} = require('googleapis');
const service = google.drive({version: 'v3', auth: authClient});
const allFiles = [];
const foldersToSearch = [folderId];
try {
while (foldersToSearch.length > 0) {
const currentFolderId = foldersToSearch.pop();
let pageToken = null;
do {
const response = await service.files.list({
q: `'${currentFolderId}' in parents and trashed = false`,
fields: 'nextPageToken, files(id, name, mimeType)',
pageSize: 1000,
supportsAllDrives: true,
includeItemsFromAllDrives: true,
pageToken: pageToken,
});
const files = response.data.files || [];
for (const file of files) {
if (file.mimeType === 'application/vnd.google-apps.folder') {
foldersToSearch.push(file.id);
} else {
allFiles.push(file);
}
}
pageToken = response.data.nextPageToken;
} while (pageToken);
}
return allFiles;
} catch (err) {
// TODO(developer): Handle error
console.error(err);
throw err;
}
}
Python
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
def search_folder_recursively(folder_id, creds):
"""Recursively searches a folder and all descendant subfolders for
files.
Args:
folder_id: The ID of the starting folder.
creds: An authorized OAuth 2.0 credentials object.
Returns:
A list of all descendant file resources.
"""
service = build("drive", "v3", credentials=creds)
all_files = []
folders_to_search = [folder_id]
try:
while folders_to_search:
current_folder_id = folders_to_search.pop()
page_token = None
while True:
response = (
service.files()
.list(
q=f"'{current_folder_id}' in parents and trashed = false",
fields="nextPageToken, files(id, name, mimeType)",
pageSize=1000,
supportsAllDrives=True,
includeItemsFromAllDrives=True,
pageToken=page_token,
)
.execute()
)
for item in response.get("files", []):
if (
item.get("mimeType")
== "application/vnd.google-apps.folder"
):
folders_to_search.append(item.get("id"))
else:
all_files.append(item)
page_token = response.get("nextPageToken")
if not page_token:
break
return all_files
except HttpError as error:
# TODO(developer): Handle error
print(f"An error occurred: {error}")
return None
البحث عن الملفات التي تحتوي على خصائص مخصصة
للبحث عن الملفات التي تحتوي على سمة ملف مخصّصة، استخدِم عبارة طلب البحث 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.FIELD_ID = 'VALUE'
إذا كانت الاستجابة ناجحة، سيحتوي نصها على جميع أمثلة الملفات التي تطابِق طلب البحث. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة البحث عن الملفات التي تحتوي على تصنيف أو قيمة حقل معيّنة.
البحث في جميع المجموعات
تلقائيًا، يتم ضبط مجموعة عناصر user على مَعلمة طلب البحث corpora
عند استخدام طريقة list. للبحث عن مجموعات عناصر أخرى، مثل تلك التي تمت مشاركتها مع domain، عليك ضبط المَعلمة corpora بشكلٍ صريح.
يمكنك البحث في مجموعات متعددة في طلب بحث واحد، ولكن إذا كانت المجموعات المدمَجة كبيرة جدًا، قد تعرض واجهة برمجة التطبيقات نتائج غير مكتملة. تحقَّق من الحقل
incompleteSearch
في نص الردّ. إذا كانت قيمته true، يعني ذلك أنّه تم حذف بعض المستندات. لحلّ هذه المشكلة، ضيّق نطاق corpora لاستخدام user أو drive.
عند استخدام مَعلمة طلب البحث
orderBy في طريقة list، تجنَّب استخدام المفتاح createdTime لطلبات البحث في مجموعات العناصر الكبيرة لأنّ ذلك يتطلّب معالجة إضافية وقد يؤدي إلى انتهاء المهلة أو حدوث مشاكل أخرى. لإجراء عملية ترتيب حسب الوقت في مجموعات العناصر الكبيرة، يمكنك استخدام modifiedTime بدلاً من ذلك لأنّه تم تحسينه للتعامل مع طلبات البحث هذه.
على سبيل المثال، اضبط orderBy على modifiedTime (أو modifiedTime desc).
إذا لم تحدّد مَعلمة طلب البحث orderBy، لن يكون هناك ترتيب فرز تلقائي وسيتم عرض العناصر بشكلٍ عشوائي.