ایجاد و مدیریت فایل ها

این راهنما نحوه ایجاد و مدیریت فایل‌ها در گوگل درایو با استفاده از API گوگل درایو را توضیح می‌دهد.

ایجاد فایل

برای ایجاد فایلی در درایو که حاوی هیچ فراداده یا محتوایی نباشد، از متد create روی منبع files بدون پارامتر استفاده کنید.

وقتی فایل را ایجاد می‌کنید، این متد یک منبع files resource) برمی‌گرداند. به فایل kind از drive.file ، یک id ، یک name "Untitled" و یک mimeType از application/octet-stream داده می‌شود. uploadType به عنوان مورد نیاز علامت‌گذاری شده است، اما به طور پیش‌فرض روی media تنظیم شده است، بنابراین لازم نیست آن را وارد کنید.

برای اطلاعات بیشتر در مورد محدودیت‌های فایل Drive، به محدودیت‌های فایل و پوشه مراجعه کنید.

استفاده از پارامتر فیلدها

اگر می‌خواهید فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید، می‌توانید پارامتر سیستمی fields را با هر متدی از منبع files تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور مجموعه‌ای پیش‌فرض از فیلدهای مختص به متد را برمی‌گرداند. برای مثال، متد list فقط فیلدهای kind ، id ، name ، mimeType و resourceKey را برای هر فایل برمی‌گرداند. برای برگرداندن فیلدهای مختلف، به بخش Return specific fields مراجعه کنید.

مالکیت فایل

وقتی فایلی با استفاده از Drive API ایجاد می‌شود، مالکیت آن به اعتبارنامه‌های احراز هویتی که توسط برنامه به روش‌های زیر استفاده می‌شود، بستگی دارد:

  • حساب کاربری (OAuth 2.0) : اگر برنامه از طرف یک کاربر احراز هویت شود، آن کاربر مالک فایل می‌شود. سپس فایل در پوشه My Drive یا یک پوشه مشخص شده قرار می‌گیرد. این فایل سهمیه فضای ذخیره‌سازی او را مصرف می‌کند.

  • حساب کاربری سرویس : اگر برنامه با استفاده از یک حساب کاربری سرویس احراز هویت شود، حساب کاربری سرویس مالک فایل خواهد بود. سپس فایل در فضای ذخیره‌سازی اختصاصی درایو حساب کاربری سرویس قرار می‌گیرد. فایل‌ها در سایر حساب‌های ذخیره‌سازی درایو نمایش داده نمی‌شوند، مگر اینکه صریحاً به اشتراک گذاشته شوند. اگر حساب کاربری سرویس حذف شود، تمام فایل‌های متعلق به آن بلافاصله حذف می‌شوند.

    اگر از یک حساب کاربری سرویس (Service Account) استفاده می‌کنید اما می‌خواهید یک حساب کاربری خاص مالک یک فایل باشد، از نمایندگی در سطح دامنه (Domain-Wide Delegation) استفاده کنید. این به حساب کاربری سرویس اجازه می‌دهد تا هویت یک کاربر را جعل کند و از طرف او فایل‌ها را ایجاد کند. برای اطلاعات بیشتر، به بخش واگذاری اختیارات در سطح دامنه به حساب کاربری سرویس مراجعه کنید.

برای اطلاعات بیشتر در مورد مجوزهای فایل، به اشتراک‌گذاری فایل‌ها، پوشه‌ها و درایوها مراجعه کنید.

ایجاد شناسه برای استفاده با فایل‌هایتان

متد generateIds در منبع files به شما امکان می‌دهد شناسه‌های فایل منحصر به فردی را از قبل تولید کنید که می‌توانند هنگام ایجاد یا کپی کردن فایل‌ها و پوشه‌ها در Drive استفاده شوند. این می‌تواند زمانی مفید باشد که نیاز دارید شناسه‌های فایل را از برنامه خود کنترل کنید، نه اینکه اجازه دهید Drive آنها را به طور خودکار اختصاص دهد.

شما می‌توانید تعداد شناسه‌های تولید شده را با استفاده از پارامتر count کوئری تنظیم کنید. اگر count تنظیم نشود، به طور پیش‌فرض ۱۰ عدد برگردانده می‌شود. حداکثر تعداد شناسه‌هایی که می‌توانید درخواست کنید ۱۰۰۰ عدد است.

همچنین می‌توانید space که می‌توان از شناسه‌ها استفاده کرد و type اقلامی که می‌توان از شناسه‌ها برای آنها استفاده کرد را تعیین کنید.

پس از تولید شناسه، می‌توان آن را از طریق فیلد id به متد create یا copy ارسال کرد. این کار تضمین می‌کند که فایل ایجاد شده یا کپی شده از شناسه از پیش تعیین شده استفاده می‌کند.

اگر فایل با موفقیت ایجاد یا کپی شود، تلاش‌های بعدی، کد وضعیت HTTP 409 Conflict را برمی‌گردانند و فایل‌های تکراری ایجاد نمی‌شوند.

توجه داشته باشید که شناسه‌های از پیش تولید شده برای ایجاد فایل‌های Google Workspace پشتیبانی نمی‌شوند، به جز انواع MIME مربوط به application/vnd.google-apps.drive-sdk و application/vnd.google-apps.folder . به طور مشابه، آپلودهایی که به تبدیل به فرمت فایل Google Workspace اشاره می‌کنند، پشتیبانی نمی‌شوند.

ایجاد فایل‌های فقط متادیتا

فایل‌های فقط متادیتا حاوی هیچ محتوایی نیستند. متادیتا داده‌هایی (مانند name ، mimeType و createdTime ) است که فایل را توصیف می‌کند. فیلدهایی مانند name ، مستقل از کاربر هستند و برای هر کاربر یکسان به نظر می‌رسند، در حالی که فیلدهایی مانند viewedByMeTime حاوی مقادیر خاص کاربر هستند.

یک نمونه از فایل فقط متادیتا، پوشه‌ای با نوع MIME application/vnd.google-apps.folder است. برای اطلاعات بیشتر، به ایجاد و پر کردن پوشه‌ها مراجعه کنید. مثال دیگر، میانبری است که به فایل دیگری در Drive با نوع MIME application/vnd.google-apps.shortcut اشاره می‌کند. برای اطلاعات بیشتر، به ایجاد میانبر برای یک فایل Drive مراجعه کنید.

مدیریت تصاویر بندانگشتی

تصاویر بندانگشتی به کاربران در شناسایی فایل‌های Drive کمک می‌کنند. Drive می‌تواند به‌طور خودکار برای انواع فایل‌های رایج، تصاویر بندانگشتی ایجاد کند یا می‌توانید یک تصویر بندانگشتی ایجاد شده توسط برنامه خود ارائه دهید. برای اطلاعات بیشتر، به بخش آپلود تصاویر بندانگشتی مراجعه کنید.

کپی کردن یک فایل موجود

برای کپی کردن یک فایل و اعمال هرگونه به‌روزرسانی درخواستی، از متد copy روی منبع files استفاده کنید. برای یافتن fileId جهت کپی کردن، از متد list استفاده کنید.

شما می‌توانید به‌روزرسانی‌ها را از طریق patch semantics اعمال کنید، به این معنی که می‌توانید تغییرات جزئی در یک منبع ایجاد کنید. شما باید فیلدهایی را که قصد تغییر آنها را دارید، به طور صریح در درخواست خود تنظیم کنید. هر فیلدی که در درخواست گنجانده نشده باشد، مقادیر موجود خود را حفظ می‌کند. برای اطلاعات بیشتر، به کار با منابع جزئی مراجعه کنید.

شما می‌توانید شناسه فایل کپی شده را با استفاده از متد generateIds از پیش تنظیم کنید. برای اطلاعات بیشتر، به بخش «شناسه‌های تولید شده برای استفاده با فایل‌هایتان» مراجعه کنید.

توجه داشته باشید که برای تأیید فراخوانی باید از یک محدوده‌ی API درایو مناسب استفاده کنید. برای اطلاعات بیشتر در مورد محدوده‌های درایو، به «انتخاب محدوده‌های API گوگل درایو» مراجعه کنید.

محدودیت‌ها و ملاحظات

هنگام آماده شدن برای کپی کردن فایل‌ها، به این محدودیت‌ها و ملاحظات توجه داشته باشید:

  • مجوزها :

    • شیء DownloadRestrictionsMetadata از منبع files تعیین می‌کند که چه کسی می‌تواند فایل را کپی کند. برای اطلاعات بیشتر، به بخش جلوگیری از دانلود، چاپ یا کپی فایل توسط کاربران مراجعه کنید.
    • منبع فیلد capabilities.canCopy تعیین می‌کند که آیا کاربر می‌تواند یک فایل را کپی کند یا خیر. برای اطلاعات بیشتر، به بخش «درک قابلیت‌های فایل» مراجعه کنید.
    • کاربری که کپی را ایجاد کرده، مالک فایل کپی شده است. هیچ تنظیمات اشتراک‌گذاری دیگری از فایل منبع کپی نمی‌شود. اگر کپی در یک پوشه مشترک ایجاد شود، مجوزهای آن پوشه را به ارث می‌برد.
    • ممکن است مالکیت یک فایل کپی‌شده تغییر کند و کپی، تنظیمات اشتراک‌گذاری فایل اصلی را به ارث نبرد. ممکن است لازم باشد این تنظیمات مجدداً تنظیم شوند.

  • مدیریت فایل :

    • بعضی از فایل‌ها، مانند میانبرهای شخص ثالث ، هرگز قابل کپی نیستند.
    • شما فقط می‌توانید یک فایل را در یک پوشه والد کپی کنید. تعیین چندین والد پشتیبانی نمی‌شود. اگر فیلد parents مشخص نشده باشد، فایل از هر والد قابل کشفی از فایل منبع ارث‌بری می‌کند.
    • اگرچه پوشه نوعی فایل است، اما نمی‌توانید یک پوشه را کپی کنید. در عوض، یک پوشه مقصد ایجاد کنید و فیلد parents فایل‌های موجود را روی پوشه مقصد تنظیم کنید. سپس می‌توانید پوشه منبع اصلی را حذف کنید.
    • مگر اینکه نام فایل جدیدی مشخص شود، متد copy فایلی با همان نام فایل اصلی تولید می‌کند.
    • استفاده بیش از حد از copy می‌تواند منجر به فراتر رفتن از محدودیت‌های سهمیه API درایو شما شود. برای اطلاعات بیشتر، به محدودیت‌های استفاده مراجعه کنید.

در اینجا چند مرحله بعدی وجود دارد که می‌توانید امتحان کنید: