این راهنما توضیح میدهد که چگونه 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 ' .
برای اطلاعات بیشتر، به جستجوی فایلهایی با برچسب یا مقدار فیلد خاص مراجعه کنید.
جستجو در پیکرهها
جستجوهایی که متد list را فراخوانی میکنند، به طور پیشفرض از corpora user استفاده میکنند. برای جستجوی پیکرههای دیگر، مانند فایلهای به اشتراک گذاشته شده با یک domain ، پارامتر corpora را تنظیم کنید.
میتوان چندین پیکره را در یک پرسوجو جستجو کرد، هرچند اگر پیکرههای ترکیبی خیلی بزرگ باشند، ممکن است نتایج ناقصی بازگردانده شوند. اگر incompleteSearch در بدنه پاسخ true باشد، همه اسناد بازگردانده نشدهاند. در این صورت، باید پرسوجوی خود را با انتخاب یک پیکره متفاوت مانند user یا drive محدود کنید.
مباحث مرتبط
- جستجوی درایوهای اشتراکی
- عبارات و عملگرهای جستجوی پرس و جو
- انواع MIME پشتیبانیشده توسط Google Workspace و Google Drive
- نقشها و مجوزها
- جستجوی فایلهایی با برچسب یا مقدار فیلد خاص