این راهنما توضیح میدهد که چگونه API گوگل درایو از چندین روش برای جستجوی فایلها و پوشهها پشتیبانی میکند.
شما میتوانید از متد list روی منبع files برای بازگرداندن تمام یا برخی از فایلها و پوشههای یک کاربر Drive استفاده کنید. همچنین میتوانید از متد list برای بازیابی fileId مورد نیاز برای برخی از متدهای منبع (مانند متد get و متد update ) استفاده کنید.
استفاده از پارامتر فیلدها
اگر میخواهید فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید، میتوانید پارامتر سیستمی fields را با هر متدی از منبع files تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور مجموعهای پیشفرض از فیلدهای مختص به متد را برمیگرداند. برای مثال، متد list فقط فیلدهای kind ، id ، name ، mimeType و resourceKey را برای هر فایل برمیگرداند. برای برگرداندن فیلدهای مختلف، به بخش Return specific fields مراجعه کنید.
دریافت فایل
برای دریافت یک فایل، از متد get روی منبع files به همراه پارامتر مسیر fileId استفاده کنید. اگر ID فایل را نمیدانید، میتوانید با استفاده از متد list ، تمام فایلها را لیست کنید .
این متد، فایل را به عنوان نمونهای از منبع files برمیگرداند. اگر پارامتر کوئری alt=media را ارائه دهید، پاسخ شامل محتوای فایل در بدنه پاسخ میشود. برای دانلود یا خروجی گرفتن فایل، به بخش دانلود و خروجی گرفتن فایلها مراجعه کنید.
برای تأیید خطر دانلود بدافزارهای شناختهشده یا سایر فایلهای مخرب ، پارامتر پرسوجوی acknowledgeAbuse » را روی true تنظیم کنید. این فیلد فقط زمانی قابل اجرا است که پارامتر alt=media تنظیم شده باشد و کاربر یا مالک فایل باشد یا یکی از سازماندهندگان درایو مشترکی که فایل در آن قرار دارد.
جستجوی تمام فایلها و پوشههای موجود در My Drive کاربر فعلی
برای برگرداندن تمام فایلها و پوشهها، از متد list بدون هیچ پارامتری استفاده کنید.
GET https://www.googleapis.com/drive/v3/files
جستجوی فایلها یا پوشههای خاص در My Drive کاربر فعلی
برای جستجوی مجموعهای خاص از فایلها یا پوشهها، از فیلد کوئری استرینگ q به همراه متد list استفاده کنید تا با ترکیب یک یا چند عبارت جستجو، فایلهایی را که میخواهید برگردانید، فیلتر کنید.
سینتکس رشته پرس و جو شامل سه بخش زیر است:
query_term operator values
کجا:
query_termعبارت یا فیلد پرسوجو برای جستجو است.operatorشرط مربوط به عبارت جستجو را مشخص میکند.values، مقادیر خاصی هستند که میخواهید برای فیلتر کردن نتایج جستجوی خود از آنها استفاده کنید.
برای مثال، رشته کوئری زیر با تنظیم نوع MIME ، جستجو را فیلتر میکند تا فقط پوشهها را برگرداند:
q: mimeType = 'application/vnd.google-apps.folder'
برای مشاهده همه اصطلاحات جستجوی فایل، به اصطلاحات جستجوی خاص فایل مراجعه کنید.
برای مشاهدهی تمام عملگرهای پرسوجویی که میتوانید برای ساخت یک پرسوجو استفاده کنید، به عملگرهای پرسوجو مراجعه کنید.
مثالهای رشته پرسوجو
جدول زیر نمونههایی از برخی رشتههای پرسوجوی پایه را فهرست میکند. کد واقعی بسته به کتابخانه کلاینتی که برای جستجوی خود استفاده میکنید، متفاوت است.
همچنین باید از کاراکترهای ویژه در نام فایلهای خود escape کنید تا مطمئن شوید که کوئری به درستی کار میکند. برای مثال، اگر نام فایلی شامل هر دو کاراکتر آپاستروف ( ' ) و بکاسلش ( "\" ) است، از بکاسلش برای escape کردن آنها استفاده کنید: name contains 'quinn\'s paper\\essay' .
| آنچه میخواهید استعلام کنید | مثال |
|---|---|
| فایلهایی با نام «سلام» | name = 'hello' |
| فایلهایی با نام حاوی کلمات "سلام" و "خداحافظ" | name contains 'hello' and name contains 'goodbye' |
| فایلهایی با نامی که شامل کلمه "hello" نیست | not name contains 'hello' |
| فایلهایی که حاوی متن «مهم» هستند و در سطل زباله قرار دارند | fullText contains 'important' and trashed = true |
| فایلهایی که شامل کلمه "سلام" هستند | 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' |
| فایلهایی که پس از تاریخ مشخصی تغییر یافتهاند (منطقه زمانی پیشفرض UTC است) | 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 استفاده میکند. همچنین برای محدود کردن بیشتر جستجو به فضای Drive ، spaces برای drive تعیین میکند. وقتی nextPageToken null را برمیگرداند، دیگر نتیجهای وجود ندارد.
جاوا
پایتون
نود جی اس
پی اچ پی
جستجوی فایلها با استفاده از یک ویژگی فایل سفارشی
برای جستجوی فایلهایی با یک ویژگی فایل سفارشی، از عبارت جستجوی 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 هنگام استفاده از روش list ، روی پارامتر پرسوجوی corpora تنظیم میشود. برای جستجوی سایر مجموعههای اقلام، مانند آنهایی که با یک domain به اشتراک گذاشته شدهاند، باید پارامتر corpora را به صراحت تنظیم کنید.
شما میتوانید چندین مجموعه داده را در یک پرسوجو جستجو کنید؛ با این حال، اگر مجموعه دادههای ترکیبی خیلی بزرگ باشد، API ممکن است نتایج ناقصی را برگرداند. فیلد incompleteSearch را در بدنه پاسخ بررسی کنید. اگر مقدار آن true باشد، یعنی برخی از اسناد حذف شدهاند. برای حل این مشکل، corpora به استفاده از user یا drive محدود کنید.
هنگام استفاده از پارامتر پرسوجوی orderBy در متد list ، از استفاده از کلید createdTime برای پرسوجوهای مربوط به مجموعههای بزرگ اقلام خودداری کنید، زیرا به پردازش اضافی نیاز دارد و ممکن است منجر به وقفههای زمانی یا سایر مشکلات شود. برای مرتبسازی مرتبط با زمان در مجموعههای بزرگ اقلام، میتوانید modifiedTime به جای آن استفاده کنید زیرا برای مدیریت این پرسوجوها بهینه شده است. به عنوان مثال، ?orderBy=modifiedTime .
اگر پارامتر query orderBy را حذف کنید، ترتیب مرتبسازی پیشفرض وجود ندارد و موارد به صورت دلخواه برگردانده میشوند.
مباحث مرتبط
- جستجوی درایوهای اشتراکی
- عبارات و عملگرهای جستجوی پرس و جو
- انواع MIME پشتیبانیشده توسط Google Workspace و Google Drive
- نقشها و مجوزها
- جستجوی فایلهایی با برچسب یا مقدار فیلد خاص