إدارة العمليات طويلة المدى

العملية التي تستغرق وقتًا طويلاً (LRO) هي طريقة لواجهة برمجة التطبيقات تستغرق وقتًا أطول لإكمالها مما هو مناسب لاستجابة واجهة برمجة التطبيقات. لا يُنصح عادةً بمحاولة إبقاء سلسلة المحادثات التي تُجري الاتصال مفتوحة أثناء تنفيذ المهمة، لأنّ ذلك يترك انطباعًا سيئًا لدى المستخدم. بدلاً من ذلك، من الأفضل تقديم نوع من الوعود للمستخدم وعدم السماح له بالرجوع لاحقًا.

تعرض Google Drive API مرجع LRO في كل مرة يتم فيها استدعاء الأسلوب download() في المرجع files لتنزيل محتوىملف، إما من خلال Drive API أو مكتبات العميل.

تُرجع الطريقة مورد operations إلى العميل. يمكنك استخدام المورد operations لجمع حالة طريقة واجهة برمجة التطبيقات بشكل غير متزامن من خلال الاستعلام عن العملية من خلال الطريقة get(). تلتزم عمليات LRO في Drive API بتصميم LRO في Google Cloud.

لمزيد من المعلومات، يُرجى الاطّلاع على العمليات التي تستغرق وقتًا طويلاً.

نظرة عامة على العملية

يوضّح الرسم البياني التالي الخطوات الأساسية لآلية عمل file.download.

1. استدعاء files.download: عندما يستدعي تطبيقك الطريقة download()، يؤدي ذلك إلى بدء طلب تنزيل الملف من خلال Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تنزيل الملفات.

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

3. بدء التنزيل: يتم إرسال طلب إلى Drive API لبدء تنزيل الملف. يمكن تقديم الطلب إلى Google Vids أو إلى أي محتوى آخر في Google Workspace.

4. بدء LRO: تبدأ عملية طويلة الأمد وتدير عملية التنزيل.

5. عرض عملية في انتظار المراجعة: تعرض واجهة برمجة التطبيقات Drive API عملية في انتظار المراجعة تحتوي على معلومات عن المستخدم الذي يقدّم الطلب والعديد من حقول البيانات الوصفية للملف.

6. الحالة الأولية في انتظار المراجعة: يتلقّى تطبيقك العملية التي في انتظار المراجعة مع حالة أولية في انتظار المراجعة هي done=null. يشير ذلك إلى أنّ الملف ليس جاهزًا للتنزيل بعد وأنّ حالة العملية في انتظار المراجعة.

7. الاتصال بـ operations.get والتحقّق من النتيجة: يتصل تطبيقك بـ get() في المُدد الزمنية المُقترَحة لفحص نتيجة العملية والحصول على أحدث حالة لعملية طويلة الأمد. إذا تم عرض الحالة "في انتظار المراجعة"done=false، يجب أن يواصل تطبيقك الاستعلام إلى أن تعرض العملية الحالة "مكتمل"done=true. بالنسبة إلى الملفات الكبيرة، من المتوقّع أن يتم الاستعلام عدة مرات. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على تفاصيل عن عملية تتعذّر إكمالها.

8. التحقّق من الحالة "في انتظار المراجعة": إذا تم عرض الحالة "في انتظار المراجعة"done=true من LRO، يعني ذلك أنّ الملف جاهز للتنزيل وأنّ حالة العملية مكتملة.

9. عرض العملية المكتملة باستخدام معرّف الموارد المنتظم (URI) للتنزيل: بعد اكتمال طلب البحث اللامحدود (LRO)، تعرض واجهة برمجة التطبيقات Drive API معرّف الموارد المنتظم (URI) للتنزيل ويصبح الملف متاحًا الآن للمستخدم.

تنزيل الملفات

لتنزيل المحتوى ضمن عملية طويلة الأمد، استخدِم الطريقة download() في المورد files. تأخذ الطريقة مَعلمات طلب البحث file_id وmime_type وrevision_id:

• مطلوب. مَعلمة طلب البحث file_id هي رقم تعريف الملف المطلوب تنزيله.

• اختيارية: تشير مَعلمة الطلب mime_type إلى نوع MIME الذي يجب أن تستخدمه الوسيلة. ولا يتوفّر إلا عند تنزيل محتوى وسائط غير ملف تعريفي (مثل مستندات Google Workspace). للحصول على قائمة كاملة بأنواع ملفّات MIME المتوافقة، يُرجى الاطّلاع على مقالة تصدير أنواع ملفّات MIME لملفات Google Workspace.

  في حال عدم ضبط نوع MIME، يتم تنزيل مستند Google Workspace باستخدام نوع MIME تلقائي. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع MIME التلقائية.

• اختيارية: مَعلمة طلب البحث revision_id هي رقم تعريف النسخة السابقة من الملف التي تريد تنزيلها. لا تتوفّر هذه الميزة إلا عند تنزيل ملفات Blob و"مستندات Google" و"جداول بيانات Google". يتم عرض رمز الخطأ INVALID_ARGUMENT عند تنزيل مراجعة معيّنة على ملفات غير متوافقة.

الطريقة download() هي الطريقة الوحيدة لتنزيل ملفات Vids بتنسيق MP4، وهي عادةً الطريقة الأنسب لتنزيل معظم ملفات الفيديو.

إنّ روابط التنزيل التي يتم إنشاؤها في "مستندات Google" أو "جداول بيانات Google" تهدف في البداية إلى إعادة التوجيه. انقر على الرابط الجديد لتنزيل الملف.

يجب أن يستخدم كلّ من طلب طريقة download() الذي يبدأ طلب الحصول على إذن الوصول إلى البيانات الوصفية (LRO) وطلب جلب عنوان URL النهائي للتنزيل مفاتيح الموارد. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى ملفات Drive التي تمت مشاركتها باستخدام رابط باستخدام مفاتيح الموارد.

يظهر هنا بروتوكول الطلب.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

استبدِل FILE_ID بـ fileId للملف الذي تريد تنزيله.

أنواع MIME التلقائية

إذا لم يتم ضبط نوع MIME عند تنزيل محتوى غير ملفّات نصية، يتم تحديد أنواع MIME التلقائية التالية:

تنزيل الردّ

عند استدعاء الطريقة download()، يتكون نص الاستجابة من مورد يمثّل عملية طويلة الأمد. تُعرِض الطريقة عادةً رابطًا لتنزيل محتوى الملف.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

تتضمّن هذه النتائج القيم التالية:

• RESOURCE_KEY: يساعد مفتاح المرجع في حماية ملفك من الوصول غير المقصود. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى ملفات Drive المشترَكة باستخدام رابط باستخدام مفاتيح الموارد.

• NAME: الاسم الذي خصصه الخادم

• DOWNLOAD_URI: معرّف الموارد المنتظم (URI) النهائي لتنزيل الملف.

يُرجى العلم أنّ الحقل partialDownloadAllowed يشير إلى ما إذا كان تحميل ملف جزئي مسموحًا به. صحيح عند تنزيل محتوى ملف ملفّ أصغر.

الحصول على تفاصيل عن عملية طويلة الأمد

العمليات التي تستغرق وقتًا طويلاً هي طلبات لإجراء قد تستغرق وقتًا طويلاً لإكمالها. عادةً ما يتم عرض عمليات التنزيل التي تم إنشاؤها حديثًا في البداية بحالة "في انتظار المراجعة" (done=null)، خاصةً ملفات Vids.

يمكنك استخدام مورد operations الذي تقدّمه واجهة برمجة التطبيقات Drive API للتحقّق من حالة طلب الحصول على إذن الوصول المؤقت (LRO) الذي تتم معالجته من خلال تضمين الاسم الفريد الذي عيّنه الخادم.

تحصل طريقة get() على أحدث حالة لعملية طويلة الأمد بشكل غير متزامن. يمكن للعملاء استخدام هذه المحاولة لفحص نتيجة العملية على فترات كما تنصح خدمة واجهة برمجة التطبيقات.

الاستعلام عن عملية تستغرق وقتًا طويلاً

لفحص طلب LRO متاح، استخدِم الأسلوب get() بشكل متكرّر إلى أن تنتهي العملية. استخدِم خوارزمية صعوديًا للرقود بين كل طلب استطلاع، مثل 10 ثوانٍ.

تظلّ طلب البحث في السجلّ متاحًا لمدة 12 ساعة على الأقل، ولكن يمكن أن يستمر في بعض الحالات لفترة أطول. تخضع هذه المدة للتغيير ويمكن أن تختلف بين أنواع الملفات. بعد انتهاء صلاحية المورد، يجب تقديم طلب جديد لطريقة download().

يجب أن تستخدم أي طلبات إلى get() مفاتيح الموارد. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى ملفات Drive التي تمت مشاركتها باستخدام رابط باستخدام مفاتيح موارد.

يتم عرض بروتوكولات الطلبات هنا.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

يُرجى العلم أنّه لا يتم عرض السمة name إلا في الردّ على طلب download(). لا تتوفّر طريقة أخرى لاستردادها لأنّ واجهة برمجة التطبيقات Drive API لا تتوافق مع الطريقة List(). في حال فقدان قيمة name، عليك إنشاء ردّ جديد من خلال طلب طريقة download() مرة أخرى.

يتألّف الردّ من طلب get() من مورد يمثّل عملية تستغرق وقتًا طويلاً. لمزيد من المعلومات، يُرجى الاطّلاع على تنزيل ملف الردّ.

عندما يحتوي الردّ على حالة مكتملة (done=true)، يعني ذلك أنّ العملية التي تستغرق وقتًا طويلاً قد اكتملت.

تنزيل نسخة سابقة

يمكنك استخدام قيمة حقل headRevisionId من المرجع files لتنزيل أحدث نسخة. يؤدي ذلك إلى جلب النسخة التي تتوافق مع البيانات الوصفية للملف الذي استرجعته سابقًا. لتنزيل بيانات جميع النُسخ السابقة منملف الذي لا يزال مخزّنًا في السحابة الإلكترونية، يمكنك استدعاء الأسلوب list() في مورد revisions باستخدام المَعلمة fileId. يؤدي ذلك إلى عرض جميع revisionIds في الملف.

لتنزيل محتوى المراجعة لملفات Blob، عليك استدعاء طريقة get() في مورد revisions باستخدام معرّف الملف المطلوب تنزيله ومعرّف المراجعة ومَعلمة عنوان URL alt=media. تُعلم مَعلمة عنوان URL alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كتنسيق استجابة بديل.

لا يمكن تنزيل المراجعات في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google" و الفيديوهات باستخدام طريقة get() مع عنوان URL alt=media . وفي حال عدم توفّر هذه البيانات، يتم إنشاء خطأ fileNotDownloadable.

معلمة عنوان URL alt=media هي مَعلمة نظام متاحة في جميع واجهات برمجة تطبيقات Google REST API. إذا كنت تستخدم مكتبة عملاء لواجهة برمجة التطبيقات Drive API، لن تحتاج إلى ضبط هذه المَعلمة صراحةً.

يظهر هنا بروتوكول الطلب.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

غيِّر القيم في السلسلة على الشكل التالي:

• FILE_ID: fileId الملف الذي تريد تنزيله
• REVISION_ID: revisionId النسخة التي تريد تنزيلها.

تؤدي المراجعات في "مستندات Google" و"رسومات Google" و"العروض التقديمية من Google" إلى الزيادة التلقائية لأرقام المراجعات. ومع ذلك، قد تتضمّن سلسلة الأرقام فواصل في حال حذف المراجعات، لذا يجب عدم الاعتماد على الأرقام التسلسلية لمحاولة استرداد المراجعات.

تحديد مشاكل عمليات إعادة التوجيه الدائم (LRO) وحلّها

عندما يتعذّر تنفيذ طلب LRO، يتضمّن ردّه رمز خطأ أساسيًا في Google Cloud.

يقدّم الجدول التالي شرحًا لسبب ظهور كل رمز وأحد الاقتراحات حول كيفية التعامل معه. بالنسبة إلى العديد من الأخطاء، يُنصح بإعادة محاولة إرسال الطلب باستخدام التراجع الدليلي.

يمكنك الاطّلاع على مزيد من المعلومات عن نموذج الأخطاء هذا وكيفية التعامل معه في دليل تصاميم واجهة برمجة التطبيقات.

مواضيع ذات صلة

• تنزيل الملفات وتصديرها
• إدارة نُسخ الملفات