این سند ملاحظات مهمی را برای نامگذاری فایلها و کار با ابردادههایی مانند متن قابل فهرستبندی و تصاویر کوچک پوشش میدهد. برای درج و بازیابی فایلها، به منبع files مراجعه کنید.
مرور کلی فراداده
در API گوگل درایو، منبع files نشاندهندهی فراداده است. برخلاف APIهایی که فراداده یک زیر-شیء است، API درایو با کل منبع files به عنوان فراداده رفتار میکند. میتوانید مستقیماً از طریق متدهای get یا list روی منبع files به فراداده دسترسی پیدا کنید.
به طور پیشفرض، متدهای get و list فقط مجموعهای جزئی از فیلدها را برمیگردانند. برای بازیابی دادههای خاص، باید پارامتر سیستم fields را در درخواست خود تعریف کنید. در صورت حذف، سرور زیرمجموعهای پیشفرض از فیلدهای خاص متد را برمیگرداند. برای مثال، متد list فقط فیلدهای kind ، id ، name ، mimeType و resourceKey را برای هر فایل برمیگرداند. برای برگرداندن فیلدهای مختلف، به بخش Return specific fields مراجعه کنید.
علاوه بر این، قابلیت مشاهده فراداده به نقش کاربر در فایل بستگی دارد. منبع permissions ، اقدامات مجاز کاربر را روی یک فایل یا پوشه تعیین نمیکند. در عوض، منبع files شامل مجموعهای از فیلدهای capabilities بولی است. API گوگل درایو این capabilities از منبع permissions مرتبط با فایل یا پوشه استخراج میکند. برای اطلاعات بیشتر، به بخش «درک قابلیتهای فایل» مراجعه کنید.
API درایو دو محدودهی محدود برای فراداده ارائه میدهد: drive.metadata و drive.metadata.readonly . محدودهی drive.metadata به شما امکان مشاهده و مدیریت فرادادههای فایل را میدهد، در حالی که drive.metadata.readonly فقط خواندنی است. هر دو به شدت دسترسی به محتوای فایل را ممنوع میکنند. برای اطلاعات بیشتر، به Choose Google Drive API scopes مراجعه کنید.
در نهایت، همیشه منطق خود را در مورد مجوزها و حوزهها تأیید کنید. برای مثال، یک کاربر ممکن است مالک یک فایل با مجوزهای کامل باشد، اما اگر برنامه شما فقط حوزه drive.metadata.readonly را داشته باشد، API درایو تلاشهایی را برای تغییر یا دانلود فایل مسدود میکند.
نام و پسوند فایلها را مشخص کنید
برنامهها باید هنگام درج فایلها با استفاده از API گوگل درایو، پسوند فایل را در ویژگی name مشخص کنند. برای مثال، عملیاتی برای درج یک فایل JPEG باید چیزی شبیه به "name": "cat.jpg" را در فراداده مشخص کند.
پاسخهای GET بعدی میتوانند شامل ویژگی فقط خواندنی fileExtension باشند که با پسوندی که در ابتدا در ویژگی name مشخص شده است، پر میشود. هنگامی که یک کاربر Google Drive درخواست دانلود یک فایل را میدهد، یا هنگامی که فایل از طریق کلاینت همگامسازی دانلود میشود، Drive یک نام فایل کامل (با پسوند) بر اساس نام ایجاد میکند. در مواردی که پسوند وجود ندارد، Drive تلاش میکند تا پسوند را بر اساس نوع MIME فایل تعیین کند.
ذخیره متن قابل فهرست بندی
درایو به طور خودکار اسناد را برای جستجو فهرست میکند وقتی نوع فایل، از جمله اسناد متنی، PDFها، تصاویر دارای متن و سایر انواع رایج را تشخیص دهد. اگر برنامه شما انواع دیگری از فایلها (مانند نقاشیها، ویدیو و میانبرها) را ذخیره میکند، میتوانید با ارائه متن قابل فهرستبندی در فیلد contentHints.indexableText فایل، قابلیت کشف آن را بهبود بخشید.
متن قابل فهرستبندی به صورت HTML فهرستبندی میشود. اگر رشته متن قابل فهرستبندی <section attribute="value1">Here's some text</section> ذخیره کنید، آنگاه "Here is some text" فهرستبندی میشود، اما "value1" نه. به همین دلیل، ذخیره XML به صورت متن قابل فهرستبندی به اندازه ذخیره HTML مفید نیست.
هنگام مشخص کردن indexableText ، موارد زیر را نیز در نظر داشته باشید:
- محدودیت حجم برای
contentHints.indexableText، ۱۲۸ کیلوبایت است. - اصطلاحات و مفاهیم کلیدی که انتظار دارید کاربر جستجو کند را ثبت کنید.
- سعی نکنید متن را بر اساس اهمیت مرتب کنید زیرا ایندکس کننده این کار را به طور موثر برای شما انجام میدهد.
- برنامه شما باید متن قابل فهرستبندی را با هر بار ذخیره بهروزرسانی کند.
- مطمئن شوید که متن با محتوا یا فرادادهی فایل مرتبط است.
این نکته آخر ممکن است بدیهی به نظر برسد، اما مهم است. اضافه کردن عبارات پرکاربرد برای نمایش اجباری یک فایل در نتایج جستجو، ایده خوبی نیست. این کار میتواند کاربران را ناامید کند و حتی ممکن است آنها را به حذف فایل ترغیب کند.
تصاویر کوچک را بارگذاری کنید
درایو به طور خودکار برای بسیاری از انواع فایلهای رایج، مانند Google Docs، Sheets و Slides، تصاویر بندانگشتی ایجاد میکند. تصاویر بندانگشتی به کاربر کمک میکنند تا فایلهای درایو را بهتر شناسایی کند.
برای انواع فایلهایی که درایو نمیتواند تصویر بندانگشتی استاندارد برای آنها ایجاد کند، میتوانید یک تصویر بندانگشتی ایجاد شده توسط برنامه خود ارائه دهید. در حین ایجاد یا بهروزرسانی فایل، با تنظیم فیلد contentHints.thumbnail در منبع files ، یک تصویر بندانگشتی بارگذاری کنید.
به طور خاص:
- فیلد
contentHints.thumbnail.imageرا روی تصویر رمزگذاری شده با base64 و نام فایل امن (به بخش ۵ RFC 4648 مراجعه کنید) تنظیم کنید. - فیلد
contentHints.thumbnail.mimeTypeرا روی نوع MIME مناسب برای تصویر بندانگشتی تنظیم کنید.
اگر درایو بتواند از فایل یک تصویر بندانگشتی ایجاد کند، از تصویر خودکار ایجاد شده استفاده میکند و هر تصویری را که ممکن است آپلود کرده باشید نادیده میگیرد. اگر نتواند تصویر بندانگشتی ایجاد کند، از تصویری که شما ارائه میدهید استفاده میکند.
تصاویر کوچک باید از این قوانین پیروی کنند:
- میتوان فایلها را با فرمتهای PNG، GIF یا JPG آپلود کرد.
- عرض توصیه شده ۱۶۰۰ پیکسل است.
- حداقل عرض ۲۲۰ پیکسل است.
- حداکثر حجم فایل ۲ مگابایت است.
- آنها باید با هر بار ذخیره، توسط برنامه شما بهروزرسانی شوند.
برای اطلاعات بیشتر، به منبع files مراجعه کنید.
بازیابی ریز عکسها
شما میتوانید فرادادهها، از جمله تصاویر بندانگشتی، را برای فایلهای Drive بازیابی کنید. اطلاعات تصاویر بندانگشتی در فیلد thumbnailLink از منبع files قرار دارد.
برگرداندن یک تصویر کوچک خاص
نمونه کد زیر یک درخواست متد get با چندین فیلد به عنوان پارامتر پرس و جو برای بازگرداندن ابرداده thumbnailLink برای یک فایل خاص را نشان میدهد. برای اطلاعات بیشتر، به «بازگرداندن فیلدهای خاص برای یک فایل» مراجعه کنید.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
به جای FILE_ID ، fileId فایل مورد نظر خود را وارد کنید.
در صورت وجود، درخواست یک URL کوتاهمدت به تصویر کوچک فایل برمیگرداند. معمولاً این لینک چند ساعت دوام میآورد. این فیلد فقط زمانی پر میشود که برنامه درخواستکننده بتواند به محتوای فایل دسترسی پیدا کند. اگر فایل به صورت عمومی به اشتراک گذاشته نشده باشد، URL برگردانده شده در thumbnailLink باید با استفاده از یک درخواست معتبر دریافت شود.
لیستی از تصاویر کوچک را برگردانید
نمونه کد زیر یک درخواست متد list با چندین فیلد به عنوان پارامتر پرس و جو برای بازگرداندن ابرداده thumbnailLink برای لیستی از فایلها را نشان میدهد. برای اطلاعات بیشتر، به Search for files and folders مراجعه کنید.
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
برای محدود کردن نتایج جستجو به یک نوع فایل خاص، یک رشته پرس و جو برای تنظیم نوع MIME اعمال کنید. به عنوان مثال، نمونه کد زیر نحوه محدود کردن لیست به فایلهای Google Sheets را نشان میدهد. برای اطلاعات بیشتر در مورد انواع MIME، به انواع MIME پشتیبانی شده توسط Google Workspace و Google Drive مراجعه کنید.
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)