این راهنما توضیح میدهد که Google Drive API چگونه از چندین روش برای جستجوی فایلها و پوشهها پشتیبانی میکند.
میتوانید از روش list در منبع files برای برگرداندن همه یا برخی از فایلها و پوشههای کاربر Drive استفاده کنید. همچنین میتوانید از روش list برای بازیابی fileId موردنیاز برای برخی روشهای منبع (مانند روشهای get و update) استفاده کنید.
استفاده از پارامتر فیلدها
اگر میخواهید فیلدهایی را که باید در پاسخ برگردانده شوند مشخص کنید، میتوانید
fields پارامتر
سیستم
را با هر روشی از منبع files تنظیم کنید. اگر پارامتر fields را حذف کنید،
سرور مجموعهای از فیلدهای پیشفرض را که مختص آن روش است برمیگرداند. برای مثال، روش
list فقط فیلدهای kind، id،
name، mimeType، و resourceKey را برای هر فایل برمیگرداند. برای برگرداندن فیلدهای
مختلف، برگرداندن فیلدهای خاص را ببینید.
دریافت فایل با شناسه
برای دریافت فایل، از روش get در منبع files با پارامتر مسیر fileId استفاده کنید.
اگر شناسه فایل را نمیدانید، میتوانید بااستفاده از روش list
همه فایلها را فهرست کنید.
این روش فایل را بهعنوان نمونهای از منبع files برمیگرداند. اگر پارامتر alt=media را ارائه دهید، پاسخ شامل محتوای فایل در بدنه پاسخ میشود. برای بارگیری فایل blob، به بارگیری محتوای فایل blob مراجعه کنید.
برای پذیرفتن خطر بارگیری بدافزارهای شناختهشده یا فایلهای سوءاستفادهگرانه دیگر، پارامتر پُرسمان acknowledgeAbuse را روی true تنظیم کنید. این فیلد فقط زمانی قابلاعمال است که
پارامتر alt=media تنظیم شده باشد و کاربر مالک فایل یا
سازماندهنده درایو مشترکی باشد که فایل در آن قرار دارد.
فهرست کردن همه فایلها و پوشهها در My Drive
از روش list بدون هیچ پارامتری برای برگرداندن همه فایلها و پوشهها در My Drive کاربر فعلی استفاده کنید.
فرمان 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 مجاز جایگزین کنید.
جستجوی فایلها و پوشههای خاص در My Drive
برای جستجوی مجموعه خاصی از فایلها یا پوشهها در My Drive کاربر فعلی، از فیلد رشته پُرسمان q با روش list استفاده کنید تا فایلها را برای بازگرداندن با ترکیب کردن یک یا چند عبارت جستجو فیلتر کنید.
نحو رشته پُرسمان شامل سه بخش زیر است:
query_term operator values
مکان:
query_termعبارت پُرسمان یا فیلدی است که باید جستجو شود.operatorشرط عبارت پرسمان را مشخص میکند.valuesمقادیر خاصی هستند که میخواهید برای فیلتر کردن نتایج جستجو استفاده کنید.
برای مثال، رشته پُرسمان زیر جستجو را فیلتر میکند تا فقط پوشهها را با تنظیم نوع MIME برگرداند:
mimeType = 'application/vnd.google-apps.folder'
برای مشاهده همه عبارات پُرسمان فایل، عبارات پُرسمان مختص فایل را ببینید.
برای مشاهده همه اپراتورهای پُرسمان که میتوانید برای ساختن پُرسمان استفاده کنید، اپراتورهای پُرسمان را ببینید.
نمونههای رشته پُرسمان
جدول زیر نمونههایی از چند رشته پُرسمان پایه را فهرست میکند. کد واقعی بسته به کتابخانه کارخواهی که برای جستجو استفاده میکنید متفاوت است.
همچنین باید نویسههای ویژه را در نام فایلهایتان محو کنید تا مطمئن شوید پُرسمان بهدرستی کار میکند. برای مثال، اگر نام فایل هم آپاستروف (') و هم واکجخط ("\") دارد، از واکجخط برای گریز از آنها استفاده کنید: name
contains 'quinn\'s paper\\essay'.
| چه چیزی را پُرسمان کنید | مثال |
|---|---|
عملگر مطابقت رشته (contains) |
|
| فایلهایی که حاوی کلمه «سلام» هستند | fullText contains 'hello' |
| فایلهایی که حاوی عبارت دقیق «سلام دنیا» هستند | fullText contains '"hello world"' |
| فایلهایی با پُرسمانی که حاوی نویسه «\» است (برای مثال، «\authors») | fullText contains '\\authors' |
| فایلهایی که نامشان حاوی «بودجه» است | name contains 'budget' |
عملگرهای برابری و نابرابری (=، !=) |
|
| فایلهایی با نام «سلام» | 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' |
عملگرهای مقایسه (>، >=، <، <=) |
|
| فایلهایی که پساز تاریخ معینی اصلاح شدهاند (منطقه زمانی پیشفرض UTC است) | modifiedTime > '2012-06-04T12:00:00' |
| فایلهای ایجادشده پساز ۱ ژانویه ۲۰۲۳ | createdTime > '2023-01-01T00:00:00' |
| فایلهایی که قبلاز ۱ ژانویه ۲۰۲۳ اصلاح شدهاند | 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) |
|
| فایلهایی که نامشان حاوی کلمات «سلام» و «خداحافظ» است | name contains 'hello' and name contains 'goodbye' |
| فایلهایی که نامشان حاوی کلمه «سلام» نیست | not name contains 'hello' |
| فایلهایی که حاوی نوشتار «مهم» هستند و در حذفشدهها قرار دارند | fullText contains 'important' and trashed = true |
| فایلهایی که حاوی کلمه «سلام» نیستند | not fullText contains 'hello' |
| فایلهای تصویر یا ویدیو که پساز تاریخ مشخصی اصلاح شدهاند | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
| فایلهای همرسانیشده با کاربر مجاز که کلمه «سلام» در نام آنها وجود دارد | sharedWithMe and name contains 'hello' |
| فایلهایی که پوشه یا میانبر هستند | mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut' |
| فایلهایی با نام «طرح پروژه» که در پوشه حذفشدهها نیستند | 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
هنگام فهرست کردن فایلها در پوشه عمومی، میتوانید درخواستها را بااستفاده از
کلید API بهجای اطلاعات کاربری 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 -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: کلید میانای API پروژه شما.
جستجوی بازگشتی پوشهها و فایلهای فرزند
عبارت پُرسمان parents فقط فایلها و پوشههای فرزند مستقیم را که در
پوشه مشخصشده قرار دارند برمیگرداند. Drive API عملگر یا پارامتر پُرسمانی برای جستجوی بازگشتی درختهای زیرپوشه فرزند در یک فراخوانی 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 را بهطور صریح
تنظیم کنید.
میتوانید چندین گردآوری اطلاعات را در یک پُرسمان جستجو کنید؛ اما اگر گردآوری اطلاعات ترکیبی
بسیار بزرگ باشد، ممکن است API نتایج ناقصی را برگرداند. فیلد
incompleteSearch
را در متن اصلی پاسخ بررسی کنید. اگر true باشد، برخیاز اسناد حذف شده است. برای
رفع این مشکل، corpora را محدود کنید تا از user یا drive استفاده کند.
هنگام استفاده از پارامتر پُرسمان
orderBy در روش list، از کلید createdTime برای پُرسمانهای
مجموعههای بزرگ مورد استفاده نکنید زیرا به پردازش اضافی نیاز دارد و ممکن است
منجر به اتمام زمان یا مشکلات دیگر شود. برای مرتبسازی براساس زمان در مجموعههای بزرگ مورد،
میتوانید بهجای آن از modifiedTime استفاده کنید زیرا برای مدیریت این پُرسمانها بهینهسازی شده است.
برای مثال، orderBy را روی modifiedTime (یا modifiedTime desc) تنظیم کنید.
اگر پارامتر پُرسمان orderBy را حذف کنید، ترتیب مرتبسازی پیشفرضی وجود ندارد و
موارد بهصورت دلخواه برگردانده میشوند.