دليل المقارنة بين الإصدارين 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).