راهنمای مقایسه 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 ) فراهم می کند.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین به‌روزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین به‌روزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Drive API v2 and v3 comparison guide\n\nThe latest Google Drive API version is v3. The performance in v3 is better because\nsearches only return a subset of fields. Use the current version unless you need\nthe [v2](/workspace/drive/api/v2/reference) collection. If you're using v2, consider\nmigrating to v3. To migrate, see [Migrate to Drive API v3](/workspace/drive/api/guides/migrate-to-v3). For a complete list of version differences, see\nthe [Drive API v2 and v3 comparison\nreference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nIf you want to continue to use v2, see the [Guide to Drive API v2](/workspace/drive/api/guides/v2-guide) amendment to learn how some instructions in the v3\nguides must be amended for v2 developers.\n\nTo learn more about Drive API v3 improvements, you can watch the\nfollowing video by Google engineers discussing the new API design. \n\nV3 improvements\n---------------\n\nTo optimize performance and reduce API behavior complexity, v3 provides these\nimprovements over the previous API version:\n\n- Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details on `fields`, see the [`files.list`](/workspace/drive/api/v3/reference/files/list) method and the [`drives.list`](/workspace/drive/api/v3/reference/drives/list) method.\n- Almost all methods that return a response now require the `fields` parameter. For a list of all methods requiring `fields`, see the [Drive API reference](/workspace/drive/api/v3/reference).\n- Resources that have duplicate capabilities were removed. Some examples:\n - The `files.list` method accomplishes the same functionality as the `Children` and `Parents` collections, so they're removed from v3.\n - The `Realtime.*` methods have been removed.\n- App Data isn't returned by default in searches. In v2, you can set the `drive.appdata` scope, and it returns application data from the `files.list` method and the [`changes.list`](/workspace/drive/api/v2/reference/changes/list) method, but it slows performance. In v3, you set the `drive.appdata` scope, and also set the query parameter `spaces=appDataFolder` to request application data.\n- All update operations use PATCH instead of PUT.\n- To export Google Documents, use the [`files.export`](/workspace/drive/api/v2/reference/files/export) method.\n- The `changes.list` method behavior is different. Instead of change IDs, use opaque page tokens. To poll the change collection, first call the [`changes.getStartPageToken`](/workspace/drive/api/v2/reference/changes/getStartPageToken) method for the initial value. For subsequent queries, the `changes.list` method returns the `newStartPageToken` value.\n- Update methods now reject requests that specify non-writable fields.\n- The v2 `exportFormats` and `importFormats` fields in the [`about`](/workspace/drive/api/reference/rest/v3/about) resource are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.\n- The v2 `appdata` and `appfolder` aliases are now `appDataFolder` in v3.\n- The `properties` resource is removed from v3. The [`files`](/workspace/drive/api/v3/reference/files) resource has the `properties` field that contains true key-value pairs. The `properties` field contains public properties, and the `appProperties` field contains private properties, so the visibility field isn't needed.\n- The `modifiedTime` field in the `files` resource updates the last time anyone modified the file. In v2, the `modifiedDate` field was only mutable on update if you set the `setModifiedDate` field.\n- The `viewedByMeTime` field in the `files` resource doesn't automatically update.\n- To import Google Docs formats, you set the appropriate target `mimeType` in the resource body. In v2, you set `?convert=true`.\n- Import operations return a 400 error if the format isn't supported.\n- Readers and commenters can't view permissions.\n- The `me` alias for permissions is removed.\n- Some functionality was available as part of the request resource but is instead available as a request parameter. For example:\n - In v2, you can use `children.delete` to remove a child file from a parent folder.\n - In v3, you use`files.update` on the child with `?removeParents=parent_id` in the URL.\n\nOther differences\n-----------------\n\nFields and parameter names are different in v3. Some examples include:\n\n- The `name` property replaces `title` in the `files` resource.\n- `Time` is the suffix for all date and time fields instead of `Date`.\n- List operations don't use the `items` field to contain the result set. The resource type provides a field for the results (such as `files` or `changes`)."]]
