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

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

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

للتعرف على مزيد من المعلومات حول التحسينات التي تم إجراؤها على الإصدار الثالث من 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 في المرجع about عبارة عن قوائم بتنسيقات الاستيراد أو التصدير المسموح بها. في الإصدار الثالث، تكون هذه العناوين خرائط من نوع MIME للأهداف المحتملة لجميع عمليات الاستيراد أو التصدير المتوافقة.
• أصبح الاسمان البديلان للبريد الإلكتروني v2 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).