دليل المقارنة بين الإصدارين 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.
• ترفض طرق التعديل الآن الطلبات التي تحدّد حقولاً غير قابلة للكتابة.
• الحقلان v2 exportFormats وimportFormats في مصدر 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).