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

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

تعرض واجهة برمجة التطبيقات Google Drive API عملية طويلة في كل مرة تستدعي فيها طريقة download على files مصدر لتنزيل محتوى ملف إما من خلال Drive API أو مكتبات العميل الخاصة به.

تعرض الطريقة مصدر operations للعميل. يمكنك استخدام مصدر operations لاسترداد حالة طريقة واجهة برمجة التطبيقات بشكل غير متزامن من خلال التحقّق من العملية باستخدام طريقة get. تلتزم العمليات الطويلة في Drive API بـ نمط تصميم العمليات الطويلة في Google Cloud.

لمزيد من المعلومات، يُرجى الاطّلاع على العمليات الطويلة.

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

يوضّح الرسم البياني التالي الخطوات عالية المستوى لكيفية عمل طريقة file.download.

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

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

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

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

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

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

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

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

9. عرض العملية المكتملة مع عنوان URI للتنزيل: بعد اكتمال العملية الطويلة، يعرض 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 هي رقم تعريف مراجعة الملف الذي سيتم تنزيله. لا تتوفّر هذه المَعلمة إلا عند تنزيل ملفات ثنائية ومستندات Google ومستندات جداول بيانات Google. تعرض رمز الخطأ INVALID_ARGUMENT عند تنزيل مراجعة معيّنة على ملفات غير متوافقة.

طريقة download هي الطريقة الوحيدة لتنزيل ملفات Vids بتنسيق MP4، وهي عادةً الأنسب لتنزيل معظم ملفات الفيديو. إذا حاولت تصدير ملفات Google Vids، ستتلقّى الخطأ fileNotExportable.

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

يجب أن يستخدم كلّ من طلب طريقة download الذي يبدأ العملية الطويلة وطلب جلب عنوان URI النهائي للتنزيل مفاتيح الموارد. لمزيد من المعلومات، يُرجى الاطّلاع على الوصول إلى ملفات 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 يشير إلى ما إذا كان مسموحًا بـ تنزيل جزئي، وتكون قيمته true عند تنزيل محتوى ملف ثنائي.

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

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

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

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

التحقّق من عملية طويلة

للتحقّق من عملية طويلة متاحة، استدعِ طريقة 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 في الملف.

لتنزيل محتوى مراجعة الملفات الثنائية، يجب استدعاء طريقة get على المصدر revisions باستخدام رقم تعريف الملف الذي سيتم تنزيله ورقم تعريف المراجعة وalt مَعلمة النظام. تخبر المَعلمة alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كشكل ردّ بديل.

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

لا يمكن تنزيل مراجعات مستندات Google وجداول بيانات Google والعروض التقديمية من Google وVids باستخدام طريقة get مع المَعلمة alt=media. بخلاف ذلك، يتم إنشاء الخطأ fileNotDownloadable.

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

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

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

• FILE_ID: fileId للملف الذي تريد تنزيله
• REVISION_ID: revisionId للمراجعة التي تريد تنزيلها

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

تحديد المشاكل في العمليات الطويلة وحلّها

عندما تفشل عملية طويلة، يتضمّن ردّها رمز خطأ أساسيًا في Google Cloud.

يعرض الجدول التالي كل رمز خطأ ورمز حالة HTTP المطابق ووصفًا واقتراحًا حول كيفية التعامل مع رمز الخطأ. بالنسبة إلى العديد من الأخطاء، يكون الإجراء المقترَح هو إعادة محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي.

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

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

• تنزيل الملفات وتصديرها