راهنمای مقایسه Drive API v2 و v3

آخرین نسخه Google Drive API نسخه 3 است. عملکرد در نسخه 3 بهتر است زیرا جستجوها فقط زیر مجموعه ای از فیلدها را برمی گرداند. از نسخه فعلی استفاده کنید مگر اینکه به مجموعه v2 نیاز داشته باشید. اگر از نسخه 2 استفاده می کنید، به نسخه 3 مهاجرت کنید. برای مهاجرت، به انتقال به Drive API نسخه 3 مراجعه کنید. برای فهرست کامل تفاوت‌های نسخه، به مرجع مقایسه Drive API v2 و v3 مراجعه کنید.

اگر می‌خواهید به استفاده از v2 ادامه دهید، به اصلاحیه Guide to Drive API v2 مراجعه کنید تا بدانید که چگونه برخی دستورالعمل‌ها در راهنماهای v3 باید برای توسعه‌دهندگان نسخه 2 اصلاح شوند.

برای کسب اطلاعات بیشتر در مورد بهبودهای Drive API v3، می‌توانید ویدیوی زیر را توسط مهندسان Google در مورد طراحی جدید API تماشا کنید.

بهبودهای V3

برای بهینه سازی عملکرد و کاهش پیچیدگی رفتار API، v3 این پیشرفت ها را نسبت به نسخه قبلی API ارائه می دهد:

  • جستجو برای فایل‌ها و درایوهای مشترک به‌طور پیش‌فرض، منابع کامل را برمی‌گرداند، فقط زیر مجموعه‌ای از فیلدهای رایج مورد استفاده برگردانده می‌شود. برای جزئیات بیشتر در مورد fields ، به روش files.list و روش drives.list مراجعه کنید.
  • تقریباً همه متدهایی که پاسخی را برمی‌گردانند اکنون به پارامتر fields نیاز دارند. برای فهرستی از همه روش‌هایی که به fields نیاز دارند، به مرجع Drive API مراجعه کنید.
  • منابعی که دارای قابلیت های تکراری هستند حذف شدند. چند نمونه:
    • متد files.list عملکردی مشابه مجموعه‌های Children و Parents را انجام می‌دهد، بنابراین آنها از نسخه 3 حذف می‌شوند.
    • متدهای Realtime.* حذف شده اند.
  • داده های برنامه به طور پیش فرض در جستجوها برگردانده نمی شود. در نسخه 2، می توانید محدوده drive.appdata را تنظیم کنید، و داده های برنامه را از روش files.list و متد changes.list برمی گرداند، اما عملکرد را کاهش می دهد. در نسخه 3، دامنه drive.appdata را تنظیم می کنید، و همچنین پارامتر query spaces=appDataFolder برای درخواست داده های برنامه تنظیم می کنید.
  • همه عملیات به روز رسانی از PATCH به جای PUT استفاده می کنند.
  • برای صادر کردن اسناد Google، از روش files.export استفاده کنید.
  • رفتار روش changes.list متفاوت است. به جای تغییر شناسه ها، از نشانه های صفحه غیر شفاف استفاده کنید. برای نظرسنجی مجموعه تغییرات، ابتدا متد changes.getStartPageToken را برای مقدار اولیه فراخوانی کنید. برای پرس و جوهای بعدی، متد changes.list مقدار newStartPageToken را برمی گرداند.
  • روش‌های به‌روزرسانی اکنون درخواست‌هایی را که فیلدهای غیرقابل نوشتن را مشخص می‌کنند، رد می‌کنند.
  • فیلدهای v2 exportFormats و importFormats در منبع about فهرستی از قالب‌های مجاز واردات یا صادرات هستند. در نسخه 3، آنها نقشه های نوع MIME از اهداف احتمالی برای همه واردات یا صادرات پشتیبانی شده هستند.
  • v2 appdata و appfolder نام مستعار اکنون appDataFolder در نسخه 3 هستند.
  • منبع properties از نسخه 3 حذف شده است. منبع files دارای فیلد properties است که شامل جفت های کلید-مقدار واقعی است. فیلد properties حاوی ویژگی‌های عمومی و فیلد appProperties حاوی ویژگی‌های خصوصی است، بنابراین به فیلد مشاهده نیازی نیست.
  • قسمت modifiedTime در منبع files آخرین باری که کسی فایل را تغییر داده به‌روزرسانی می‌شود. در نسخه 2، فیلد modifiedDate تنها در صورت تنظیم فیلد setModifiedDate در به‌روزرسانی قابل تغییر بود.
  • فیلد viewedByMeTime در منبع files به طور خودکار به روز نمی شود.
  • برای وارد کردن قالب‌های Google Docs، mimeType مناسب را در بدنه منبع تنظیم می‌کنید. در نسخه 2، ?convert=true تنظیم کردید.
  • اگر فرمت پشتیبانی نشود، عملیات واردات یک خطای 400 برمی‌گرداند.
  • خوانندگان و نظر دهندگان نمی توانند مجوزها را مشاهده کنند.
  • نام مستعار me برای مجوزها حذف شده است.
  • برخی از عملکردها به عنوان بخشی از منبع درخواست در دسترس بود اما در عوض به عنوان پارامتر درخواست در دسترس است. مثلا:
    • در نسخه 2، می توانید از children.delete برای حذف یک فایل فرزند از پوشه والد استفاده کنید.
    • در نسخه 3، از files.update روی فرزند با ?removeParents=parent_id در URL استفاده می کنید.

تفاوت های دیگر

نام فیلدها و پارامترها در v3 متفاوت است. برخی از نمونه ها عبارتند از:

  • ویژگی name جایگزین title در منبع files می شود.
  • Time پسوند تمام فیلدهای تاریخ و زمان به جای Date است.
  • عملیات فهرست از فیلد items برای حاوی مجموعه نتایج استفاده نمی کند. نوع منبع یک فیلد برای نتایج (مانند files یا changes ) فراهم می کند.