دليل المقارنة بين الإصدارين 2 و3 من واجهة برمجة تطبيقات Drive

أحدث إصدار من Google Drive API هو الإصدار 3. يكون الأداء في الإصدار 3 أفضل لأن عمليات البحث لا تعرض سوى مجموعة فرعية من الحقول. استخدِم الإصدار الحالي ما لم تكن بحاجة إلى مجموعة v2. إذا كنت تستخدم الإصدار 2، ففكر في الانتقال إلى الإصدار 3. لنقل البيانات، يُرجى الاطّلاع على نقل البيانات إلى الإصدار 3 من Drive API. للحصول على قائمة كاملة بالاختلافات بين الإصدارات، يُرجى الاطّلاع على مرجع المقارنة للإصدارَين 2 و3 من Drive API.

إذا أردت مواصلة استخدام الإصدار 2، يمكنك الاطّلاع على تعديل دليل الإصدار 2 من Drive API للتعرّف على كيفية تعديل بعض التعليمات الواردة في هذه الإرشادات للمطوّرين للإصدار 2.

لمعرفة المزيد حول تحسينات الإصدار الثالث من Drive API، يمكنك مشاهدة الفيديو التالي الذي أعدّه مهندسو Google وهو يناقش تصميم واجهة برمجة التطبيقات الجديد.

تحسينات الإصدار الثالث

لتحسين الأداء وتقليل تعقيد سلوك واجهة برمجة التطبيقات، يوفّر الإصدار 3 هذه التحسينات مقارنةً بإصدار واجهة برمجة التطبيقات السابق:

• لا تعرض عمليات البحث عن الملفات ومساحات التخزين السحابي المشتركة الموارد الكاملة تلقائيًا، ولكن لا يتم عرض سوى مجموعة فرعية من الحقول الشائعة الاستخدام. لمزيد من التفاصيل عن fields، يمكنك الاطّلاع على طريقة files.list وطريقة drives.list.
• تتطلب جميع الطرق تقريبًا التي تعرض استجابة الآن المعلَمة fields. للحصول على قائمة بجميع الطرق التي تتطلب fields، يمكنك الاطّلاع على مرجع واجهة برمجة تطبيقات Drive.
• تمت إزالة المراجع التي تحتوي على إمكانيات مكرّرة. في ما يلي بعض الأمثلة:
  • تنفِّذ الطريقة 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 في المورد about قوائم بتنسيقات الاستيراد أو التصدير المسموح بها. في الإصدار 3، تكون خرائط من نوع MIME للأهداف المحتملة لجميع عمليات الاستيراد أو التصدير المدعومة.
• أصبح اسما الإصدارين 2 appdata وappfolder البديلَين الآن 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).