دليل المقارنة بين الإصدارين 2 و3 من واجهة برمجة تطبيقات Drive
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
أحدث إصدار من Google Drive API هو الإصدار 3. يكون الأداء في الإصدار 3 أفضل لأنّ عمليات البحث تعرض مجموعة فرعية فقط من الحقول. استخدِم الإصدار الحالي ما لم تكن بحاجة إلى مجموعة v2. إذا كنت تستخدم الإصدار 2، ننصحك بالانتقال إلى الإصدار 3. لإجراء عملية نقل البيانات، يُرجى الاطّلاع على نقل البيانات إلى الإصدار 3 من Drive API. للاطّلاع على قائمة كاملة بالاختلافات بين الإصدارين، يُرجى الرجوع إلى مرجع مقارنة الإصدارين 2 و3 من Drive API.
إذا أردت مواصلة استخدام الإصدار 2، يمكنك الاطّلاع على التعديل دليل الإصدار 2 من Drive API لمعرفة كيفية تعديل بعض التعليمات الواردة في أدلة الإصدار 3 لتناسب مطوّري الإصدار 2.
لمزيد من المعلومات حول تحسينات الإصدار 3 من Drive API، يمكنك مشاهدة الفيديو التالي الذي يتضمّن مناقشة من مهندسي Google حول تصميم واجهة برمجة التطبيقات الجديدة.
تحسينات الإصدار 3
لتحسين الأداء وتقليل تعقيد سلوك واجهة برمجة التطبيقات، يقدّم الإصدار 3 التحسينات التالية مقارنةً بإصدار واجهة برمجة التطبيقات السابق:
- لا تعرض عمليات البحث عن الملفات ومساحات التخزين السحابي المشتركة الموارد الكاملة تلقائيًا، بل تعرض مجموعة فرعية فقط من الحقول الشائعة الاستخدام. لمزيد من التفاصيل حول
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،
وكذلك ضبط مَعلمة طلب البحث spaces=appDataFolder لطلب
بيانات التطبيق.
- تستخدم جميع عمليات التعديل الأمر PATCH بدلاً من PUT.
- لتصدير مستندات Google، استخدِم طريقة
files.export.
- يختلف سلوك الطريقة
changes.list. بدلاً من تغيير المعرّفات، استخدِم رموزًا مميّزة غير شفافة للصفحات. لإجراء استطلاع بشأن مجموعة التغييرات، عليك أولاً استدعاء الطريقة
changes.getStartPageToken
للحصول على القيمة الأولية. بالنسبة إلى طلبات البحث اللاحقة، تعرض الطريقة changes.list القيمة newStartPageToken.
- ترفض طرق التعديل الآن الطلبات التي تحدّد حقولاً غير قابلة للكتابة.
- الحقلان
exportFormats وimportFormats في الإصدار 2 من المورد
about هما قائمتان بتنسيقات الاستيراد أو التصدير المسموح بها. في الإصدار 3، تكون عبارة عن خرائط لأنواع MIME الخاصة بالأهداف المحتملة لجميع عمليات الاستيراد أو التصدير المتوافقة.
- أصبحت الأسماء المستعارة
appdata وappfolder في الإصدار 2 الآن appDataFolder في الإصدار 3.
- تمت إزالة المرجع
properties من الإصدار 3. يحتوي المرجع files على الحقل properties الذي يتضمّن أزواج المفاتيح والقيم الصحيحة. يحتوي الحقل properties على خصائص عامة، ويحتوي الحقل appProperties على خصائص خاصة، لذا لا حاجة إلى حقل مستوى العرض.
- يعدّل الحقل
modifiedTime في مورد files آخر مرة عدّل فيها أي مستخدم الملف. في الإصدار 2، كان الحقل modifiedDate قابلاً للتعديل عند التحديث فقط إذا تم ضبط الحقل setModifiedDate.
- لا يتم تعديل الحقل
viewedByMeTime في المورد files تلقائيًا.
- لاستيراد تنسيقات "مستندات Google"، عليك ضبط الهدف المناسب
mimeType
في نص المرجع. في الإصدار 2، يمكنك ضبط ?convert=true.
- تعرض عمليات الاستيراد الخطأ 400 إذا كان التنسيق غير متوافق.
- لا يمكن للقراء والمعلِّقين الاطّلاع على الأذونات.
- تمت إزالة الاسم المستعار
me للأذونات.
- كانت بعض الوظائف متاحة كجزء من مورد الطلب، ولكنها أصبحت متاحة كمعلَمة طلب. على سبيل المثال:
- في الإصدار 2، يمكنك استخدام
children.delete لإزالة ملف فرعي من مجلد رئيسي.
- في الإصدار 3، يمكنك استخدام
files.update على العنصر الفرعي مع ?removeParents=parent_id في عنوان URL.
الاختلافات الأخرى
تختلف الحقول وأسماء المَعلمات في الإصدار 3. ومن الأمثلة على ذلك:
- تحلّ السمة
name محلّ title في المرجع files.
Time هو اللاحقة لجميع حقول التاريخ والوقت بدلاً من Date.- لا تستخدم عمليات القائمة الحقل
items لاحتواء مجموعة النتائج. يوفر نوع المورد حقلاً للنتائج (مثل files أو changes).
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة 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`)."]]
